MY_DATABASE_URL
connection_string: ${MY_DATABASE_URL}
connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db}
martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] diff --git a/development.html b/development.html index 74e868c54..61517e924 100644 --- a/development.html +++ b/development.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,25 +180,28 @@ Martin Tile Server Documentation Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. @@ -208,6 +211,9 @@ Development + + + @@ -219,6 +225,9 @@ Development + + + diff --git a/env-vars.html b/env-vars.html index a0b9a9aa5..39ce822e6 100644 --- a/env-vars.html +++ b/env-vars.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/images/qgis_add_to_layers.png b/images/qgis_add_to_layers.png new file mode 100644 index 000000000..68d6097a9 Binary files /dev/null and b/images/qgis_add_to_layers.png differ diff --git a/images/qgis_add_vector_tile.png b/images/qgis_add_vector_tile.png new file mode 100644 index 000000000..de707e506 Binary files /dev/null and b/images/qgis_add_vector_tile.png differ diff --git a/images/qgis_add_vector_tile_options.png b/images/qgis_add_vector_tile_options.png new file mode 100644 index 000000000..2b912926d Binary files /dev/null and b/images/qgis_add_vector_tile_options.png differ diff --git a/images/qgis_shows_in_the_map.png b/images/qgis_shows_in_the_map.png new file mode 100644 index 000000000..84816fe9f Binary files /dev/null and b/images/qgis_shows_in_the_map.png differ diff --git a/index.html b/index.html index ffbba9a5e..d54482e77 100644 --- a/index.html +++ b/index.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/installation.html b/installation.html index eccdad31f..c8fd825ab 100644 --- a/installation.html +++ b/installation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,40 +180,59 @@ Martin Tile Server Documentation Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help - + @@ -227,7 +246,7 @@ Docker - + diff --git a/introduction.html b/introduction.html index ffbba9a5e..d54482e77 100644 --- a/introduction.html +++ b/introduction.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/martin-as-a-library.html b/martin-as-a-library.html new file mode 100644 index 000000000..f4ae680cb --- /dev/null +++ b/martin-as-a-library.html @@ -0,0 +1,236 @@ + + + + + + Martin as a library - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/martin-cp.html b/martin-cp.html index aaef21c63..06acb5b2b 100644 --- a/martin-cp.html +++ b/martin-cp.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,11 +180,17 @@ Martin Tile Server Documentation Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
martin --config config.yaml
You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose.
--save-config
martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] diff --git a/development.html b/development.html index 74e868c54..61517e924 100644 --- a/development.html +++ b/development.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,25 +180,28 @@ Martin Tile Server Documentation Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. @@ -208,6 +211,9 @@ Development + + + @@ -219,6 +225,9 @@ Development + + + diff --git a/env-vars.html b/env-vars.html index a0b9a9aa5..39ce822e6 100644 --- a/env-vars.html +++ b/env-vars.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/images/qgis_add_to_layers.png b/images/qgis_add_to_layers.png new file mode 100644 index 000000000..68d6097a9 Binary files /dev/null and b/images/qgis_add_to_layers.png differ diff --git a/images/qgis_add_vector_tile.png b/images/qgis_add_vector_tile.png new file mode 100644 index 000000000..de707e506 Binary files /dev/null and b/images/qgis_add_vector_tile.png differ diff --git a/images/qgis_add_vector_tile_options.png b/images/qgis_add_vector_tile_options.png new file mode 100644 index 000000000..2b912926d Binary files /dev/null and b/images/qgis_add_vector_tile_options.png differ diff --git a/images/qgis_shows_in_the_map.png b/images/qgis_shows_in_the_map.png new file mode 100644 index 000000000..84816fe9f Binary files /dev/null and b/images/qgis_shows_in_the_map.png differ diff --git a/index.html b/index.html index ffbba9a5e..d54482e77 100644 --- a/index.html +++ b/index.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/installation.html b/installation.html index eccdad31f..c8fd825ab 100644 --- a/installation.html +++ b/installation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,40 +180,59 @@ Martin Tile Server Documentation Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help - + @@ -227,7 +246,7 @@ Docker - + diff --git a/introduction.html b/introduction.html index ffbba9a5e..d54482e77 100644 --- a/introduction.html +++ b/introduction.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/martin-as-a-library.html b/martin-as-a-library.html new file mode 100644 index 000000000..f4ae680cb --- /dev/null +++ b/martin-as-a-library.html @@ -0,0 +1,236 @@ + + + + + + Martin as a library - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/martin-cp.html b/martin-cp.html index aaef21c63..06acb5b2b 100644 --- a/martin-cp.html +++ b/martin-cp.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,11 +180,17 @@ Martin Tile Server Documentation Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
martin ... ... ... --save-config config.yaml
# Connection keep alive timeout [default: 75] diff --git a/development.html b/development.html index 74e868c54..61517e924 100644 --- a/development.html +++ b/development.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,25 +180,28 @@ Martin Tile Server Documentation Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. @@ -208,6 +211,9 @@ Development + + + @@ -219,6 +225,9 @@ Development + + + diff --git a/env-vars.html b/env-vars.html index a0b9a9aa5..39ce822e6 100644 --- a/env-vars.html +++ b/env-vars.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/images/qgis_add_to_layers.png b/images/qgis_add_to_layers.png new file mode 100644 index 000000000..68d6097a9 Binary files /dev/null and b/images/qgis_add_to_layers.png differ diff --git a/images/qgis_add_vector_tile.png b/images/qgis_add_vector_tile.png new file mode 100644 index 000000000..de707e506 Binary files /dev/null and b/images/qgis_add_vector_tile.png differ diff --git a/images/qgis_add_vector_tile_options.png b/images/qgis_add_vector_tile_options.png new file mode 100644 index 000000000..2b912926d Binary files /dev/null and b/images/qgis_add_vector_tile_options.png differ diff --git a/images/qgis_shows_in_the_map.png b/images/qgis_shows_in_the_map.png new file mode 100644 index 000000000..84816fe9f Binary files /dev/null and b/images/qgis_shows_in_the_map.png differ diff --git a/index.html b/index.html index ffbba9a5e..d54482e77 100644 --- a/index.html +++ b/index.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/installation.html b/installation.html index eccdad31f..c8fd825ab 100644 --- a/installation.html +++ b/installation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,40 +180,59 @@ Martin Tile Server Documentation Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help - + @@ -227,7 +246,7 @@ Docker - + diff --git a/introduction.html b/introduction.html index ffbba9a5e..d54482e77 100644 --- a/introduction.html +++ b/introduction.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/martin-as-a-library.html b/martin-as-a-library.html new file mode 100644 index 000000000..f4ae680cb --- /dev/null +++ b/martin-as-a-library.html @@ -0,0 +1,236 @@ + + + + + + Martin as a library - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/martin-cp.html b/martin-cp.html index aaef21c63..06acb5b2b 100644 --- a/martin-cp.html +++ b/martin-cp.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,11 +180,17 @@ Martin Tile Server Documentation Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo.
upstream
main
git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands.
Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo.
git clone https://github.com/maplibre/martin.git -o upstream cd martin
Fork Martin repo into your own GitHub account, and add your fork as a remote
git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands.
git remote add origin _URL_OF_YOUR_FORK_
Install docker and docker-compose
# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands.
# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose
Install a few required libs and tools:
# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands.
# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file
Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source:
cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands.
Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source:
cargo install just --locked
When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands.
just prepare-sqlite
just
When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands.
If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended.
If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended.
Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles.
-v
DATABASE_URL
export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml +
You can download martin from GitHub releases page.
If you install Rust, you can build martin from source with Cargo:
cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help - + @@ -227,7 +246,7 @@ Docker - + diff --git a/introduction.html b/introduction.html index ffbba9a5e..d54482e77 100644 --- a/introduction.html +++ b/introduction.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/martin-as-a-library.html b/martin-as-a-library.html new file mode 100644 index 000000000..f4ae680cb --- /dev/null +++ b/martin-as-a-library.html @@ -0,0 +1,236 @@ + + + + + + Martin as a library - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/martin-cp.html b/martin-cp.html index aaef21c63..06acb5b2b 100644 --- a/martin-cp.html +++ b/martin-cp.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,11 +180,17 @@ Martin Tile Server Documentation Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Rust users can install pre-built martin binary +with cargo-binstall and cargo.
cargo
cargo install cargo-binstall +cargo binstall martin martin --help
To install with apt source and others, We need your help +to improve packaging for various platforms.
If you are using macOS and Homebrew you can install martin using Homebrew tap.
brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help - + @@ -227,7 +246,7 @@ Docker - + diff --git a/introduction.html b/introduction.html index ffbba9a5e..d54482e77 100644 --- a/introduction.html +++ b/introduction.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/martin-as-a-library.html b/martin-as-a-library.html new file mode 100644 index 000000000..f4ae680cb --- /dev/null +++ b/martin-as-a-library.html @@ -0,0 +1,236 @@ + + + + + + Martin as a library - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/martin-cp.html b/martin-cp.html index aaef21c63..06acb5b2b 100644 --- a/martin-cp.html +++ b/martin-cp.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,11 +180,17 @@ Martin Tile Server Documentation Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
brew tap maplibre/martin brew install martin +martin --help
Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles.
export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help - + @@ -227,7 +246,7 @@ Docker - + diff --git a/introduction.html b/introduction.html index ffbba9a5e..d54482e77 100644 --- a/introduction.html +++ b/introduction.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -196,7 +196,7 @@ Martin Tile Server Documentation - + @@ -207,7 +207,7 @@ Martin Tile Server Documentation - + diff --git a/martin-as-a-library.html b/martin-as-a-library.html new file mode 100644 index 000000000..f4ae680cb --- /dev/null +++ b/martin-as-a-library.html @@ -0,0 +1,236 @@ + + + + + + Martin as a library - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/martin-cp.html b/martin-cp.html index aaef21c63..06acb5b2b 100644 --- a/martin-cp.html +++ b/martin-cp.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,11 +180,17 @@ Martin Tile Server Documentation Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb +
cargo install martin --locked +martin --help
Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features:
martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
martin-cp
After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command.
agg_tiles_hash
--skip-agg-tiles-hash
mbtiles validate
martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources.
After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command.
This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world.
my_table
tileset.mbtiles
martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world.
martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ diff --git a/mbtiles-copy.html b/mbtiles-copy.html index e79b1e9db..ed23289af 100644 --- a/mbtiles-copy.html +++ b/mbtiles-copy.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,23 +182,24 @@ Martin Tile Server Documentation Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles copy
Copy command copies an mbtiles file, optionally filtering its content by zoom levels.
mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10
This command can also be used to generate files of different supported schema.
mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash
mbtiles copy --diff-with-file
This option is identical to using mbtiles diff .... The following commands two are equivalent:
mbtiles diff ...
mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles
mbtiles copy --apply-patch
Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified.
copy --diff-with-file
mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles diff --git a/mbtiles-diff.html b/mbtiles-diff.html index e564776dd..9d1a51025 100644 --- a/mbtiles-diff.html +++ b/mbtiles-diff.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -190,7 +190,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified.
mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles
mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
apply-patch
agg_tiles_hash_after_apply
# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -213,7 +213,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles apply-patch src_file.mbtiles diff_file.mbtiles
Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -221,7 +221,7 @@
sqlite3
sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ diff --git a/mbtiles-meta.html b/mbtiles-meta.html index bdddd0f70..85d41f2c4 100644 --- a/mbtiles-meta.html +++ b/mbtiles-meta.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,8 +181,10 @@ Martin Tile Server Documentation MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" diff --git a/mbtiles-schema.html b/mbtiles-schema.html index dee866cd7..67f3f7cc6 100644 --- a/mbtiles-schema.html +++ b/mbtiles-schema.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/mbtiles-validation.html b/mbtiles-validation.html index ee7eae517..6eda188a1 100644 --- a/mbtiles-validation.html +++ b/mbtiles-validation.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,28 +180,46 @@ Martin Tile Server Documentation MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. diff --git a/pg-connections.html b/pg-connections.html index 60f1eb5a7..84f3cb2b2 100644 --- a/pg-connections.html +++ b/pg-connections.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/print.html b/print.html index c12daebfe..9d5f8366a 100644 --- a/print.html +++ b/print.html @@ -89,7 +89,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -188,44 +188,184 @@ Martin Tile Server Documentation +Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + +Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. +View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + Prerequisites -If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. -Binary Distributions +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+. Postgis v3.1+ is recommended. +Docker +Martin is also available as a Docker image. You could either share a configuration +file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by +passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. +export PGPASSWORD=postgres # secret! + +docker run -p 3000:3000 \ + -e PGPASSWORD \ + -e DATABASE_URL=postgresql://user@host:port/db \ + -v /path/to/config/dir:/config \ + ghcr.io/maplibre/martin --config /config/config.yaml + +From Binary Distributions Manually You can download martin from GitHub releases page. -PlatformDownloads (latest) -Linux64-bit -macOS64-bit -Windows64-bit +Platformx64ARM-64 +Linux.tar.gz (gnu).tar.gz (musl).deb.tar.gz (musl) +macOS.tar.gz.tar.gz +Windows.zip -Building with Cargo -If you install Rust, you can build martin from source with Cargo: -cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level.
mbtiles summary
MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset"
Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level.
MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -199,16 +201,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85
Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection.
mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset"
Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection.
mbtiles meta-all my_file.mbtiles
Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file:
description
mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset"
Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file:
mbtiles meta-get my_file.mbtiles description
Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset:
A vector tile dataset
mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset"
Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset:
mbtiles meta-set my_file.mbtiles description "A vector tile dataset"
The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code.
mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist.
The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code.
mbtiles validate src_file.mbtiles
The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick.
validate
PRAGMA integrity_check
ok
--integrity-check
full
quick
The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick.
The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes.
tiles
metadata
The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes.
If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema).
.mbtiles
tile_data
tile_hash
tile_id
A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout.
mbtiles
If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema).
A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout.
Per-tile validation is not available for the flat schema, and will be skipped.
flat
Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash.
The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate:
md5_concat_hex
Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash.
The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate:
md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data)
In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail.
The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist.
--agg-hash update
In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail.
The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist.
Choose your operating system to get started with Martin tile server
mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 +
See quick start with QGIS for instructions on how to view the map.
Download some demo tiles.
Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type.
Extract content of both files and place them in a same directory.
Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located.
martin
world_cities.mbtiles
Run the following command to start Martin with the demo data:
# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles +
Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip
# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles +
Download, install, and run QGIS for your platform
Add a new Vector Tiles connection
Vector Tiles
+ +
In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK.
Vector Tile Connection
http://localhost:3000/martin/{z}/{x}/{y}.pbf
OK
In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project.
Add Layer to Project
The map should now be visible in the QGIS map view.
cargo install martin --locked +Rust users can install pre-built martin binary +with cargo-binstall and cargo. +cargo install cargo-binstall +cargo binstall martin martin --help -Homebrew +From package +To install with apt source and others, We need your help +to improve packaging for various platforms. +Homebrew If you are using macOS and Homebrew you can install martin using Homebrew tap. -brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
brew tap maplibre/martin +brew tap maplibre/martin brew install martin +martin --help -Docker -Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing DATABASE_URL or specifying the .mbtiles/.pmtiles files or URLs to .pmtiles. -export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
export PGPASSWORD=postgres # secret! -docker run -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - -v /path/to/config/dir:/config \ - ghcr.io/maplibre/martin --config /config/config.yaml +Debian Packages(x86_64) manually +curl -O https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb +sudo dpkg -i ./martin-Debian-x86_64.deb +martin --help +rm ./martin-Debian-x86_64.deb + +Building From source +If you install Rust, you can build martin from source with Cargo: +cargo install martin --locked +martin --help Usage -Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. -martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Martin requires at least one PostgreSQL connection string or a tile source file as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable.
martin postgresql://postgres@localhost/db +Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable. +martin postgresql://postgres@localhost/db -Martin provides TileJSON endpoint for each geospatial-enabled table in your database. +Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database. Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Martin requires at least one PostgreSQL connection string or a tile source file +as a command-line argument. A PG connection string can also be passed via the DATABASE_URL environment variable.
martin postgresql://postgres@localhost/db
Martin provides TileJSON endpoint for each geospatial-enabled table in your database.
Martin provides TileJSON endpoint for +each geospatial-enabled table in your +database.
You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information.
martin --help
cargo run -- --help
Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... @@ -299,42 +439,45 @@ Docker Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
You can use official Docker image ghcr.io/maplibre/martin
ghcr.io/maplibre/martin
docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin
You can expose local files to the Docker container using the -v flag.
docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files
If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network.
localhost
For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network.
--net=host
-p
docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network.
For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network.
docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin
For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service.
host.docker.internal
docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin
For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service.
docker.for.win.localhost
docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin
You can use example docker-compose.yml file as a reference
docker-compose.yml
You can use example docker-compose.yml +file as a reference
services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -358,10 +501,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker compose up -d db
Then, after db service is ready to accept connections, you can start martin
db
docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 Using with NGINX @@ -570,13 +713,16 @@ TODO Teach Martin how to set the Cache-Control and Etag headers for better defaults. Troubleshooting -Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives. +Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives. This will enable debug logging for all modules: -export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker compose up -d martin
By default, Martin will be available at localhost:3000
Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of logging directives.
RUST_LOG
Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is +controlled via the RUST_LOG environment variable. The value of this environment variable is a comma-separated list of +logging directives.
This will enable debug logging for all modules:
export RUST_LOG=debug +export RUST_LOG=debug martin postgresql://postgres@localhost/db -While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules: -export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
export RUST_LOG=debug martin postgresql://postgres@localhost/db
While this will only enable verbose logging for the actix_web module and enable debug logging for the martin and tokio_postgres modules:
actix_web
tokio_postgres
export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug +While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules: +export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db Configuration File @@ -585,11 +731,11 @@ TODO contain environment variables, which will be expanded before parsing. For example, to use MY_DATABASE_URL in your config file: connection_string: ${MY_DATABASE_URL}, or with a default connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db} -martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
While this will only enable verbose logging for the actix_web module and enable debug logging for the martin +and tokio_postgres modules:
export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db
martin --config config.yaml +martin --config config.yaml You may wish to auto-generate a config file with --save-config argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don’t want to expose. -martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
martin ... ... ... --save-config config.yaml +martin ... ... ... --save-config config.yaml Config Example # Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
# Connection keep alive timeout [default: 75] @@ -835,7 +981,12 @@ PostgreSQL Function Sources -Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash). +Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash). ArgumentTypeDescription z (or zoom)integerTile zoom parameter xintegerTile x parameter @@ -844,7 +995,8 @@ Simple Function -For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source: +For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source: CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Function Source is a database function which can be used to query vector tiles. When started, Martin will look for the functions with a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a record with a single bytea field, or a record with two fields of types bytea and text, where the text field is an etag key (i.e. md5 hash).
z integer
zoom integer
x integer
y integer
query json
bytea
text
Function Source is a database function which can be used to +query vector tiles. When started, Martin will look for the functions with +a suitable signature. A function that takes z integer (or zoom integer), x integer, y integer, and an +optional query json and returns bytea, can be used as a Function Source. Alternatively the function could return a +record with a single bytea field, or a record with two fields of types bytea and text, where the text field is +an etag key (i.e. md5 hash).
For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function Source:
table_source
4326
For example, if you have a table table_source in WGS84 (4326 SRID), then you can use this function as a Function +Source:
CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$ @@ -888,11 +1040,14 @@ curl localhost:3000/function_zxy_query/0/0/0?token=martin +The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g. +curl localhost:3000/function_zxy_query/0/0/0?token=martin -You can also use urlencoded params to encode complex values: -curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
The query_params argument is a JSON representation of the tile request query params. Query params could be passed as +simple query values, e.g.
query_params
curl localhost:3000/function_zxy_query/0/0/0?token=martin
You can also use urlencoded params to encode complex values:
curl \ +You can also +use urlencoded +params to encode complex values: +curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int; Modifying TileJSON -Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host): +Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host): { "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod } TileJSON in SQL Comments -To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON. -Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments. +To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON. +Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments. DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
You can also +use urlencoded +params to encode complex values:
curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ --data-urlencode 'stringParam=value' \ @@ -913,7 +1068,11 @@ ...WHERE answer = (query_params->'objectParam'->>'answer')::int;
Martin will automatically generate a basic TileJSON manifest for each function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, and bounds (if they were specified via one of the configuration methods). For example, if there is a function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be automatically adjusted to match the request host):
minzoom
maxzoom
bounds
public.function_zxy_query_jsonb
TileJSON
Martin will automatically generate a basic TileJSON manifest for each +function source that will contain the name and description of the function, plus optionally minzoom, maxzoom, +and bounds (if they were specified via one of the configuration methods). For example, if there is a +function public.function_zxy_query_jsonb, the default TileJSON might look like this (note that URL will be +automatically adjusted to match the request host):
{ "tilejson": "3.0.0", "tiles": [ @@ -924,8 +1083,11 @@ Mod }
To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will merge function comment into the generated TileJSON using JSON Merge patch. The following example adds attribution and version fields to the TileJSON.
attribution
version
Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an error). You can use other methods of creating SQL comments.
EXECUTE
To modify automatically generated TileJSON, you can add a valid JSON as an SQL comment on the function. Martin will +merge function comment into the generated TileJSON using JSON Merge patch. +The following example adds attribution and version fields to the TileJSON.
Note: This example uses EXECUTE to ensure that the comment is a valid JSON (or else PostgreSQL will throw an +error). You can use other methods of creating SQL comments.
DO $do$ BEGIN EXECUTE 'COMMENT ON FUNCTION my_function_name IS $tj$' || $$ { @@ -945,30 +1107,43 @@ MBTiles and PMTiles File Sources -Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: -martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example:
*.mbtiles
*.pmtiles
martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles +Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example: +martin /path/to/mbtiles/file.mbtiles /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. +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. Composite Sources -Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN} +Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN} Each source in a composite source can be accessed with its {source_name} as a source-layer property. -Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. +Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}. For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y} -# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Martin can serve any type of tiles from PMTile +and MBTile files. To serve a file from CLI, simply put the path to the file or +the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example:
martin /path/to/mbtiles/file.mbtiles /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.
--save-config my-config.yaml
--config my-config.yaml
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.
Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by comma {source1},...,{sourceN}
{source1},...,{sourceN}
Composite Sources allows combining multiple sources into one. Composite Source consists of multiple sources separated by +comma {source1},...,{sourceN}
Each source in a composite source can be accessed with its {source_name} as a source-layer property.
{source_name}
source-layer
Composite source TileJSON endpoint is available at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}.
/{source1},...,{sourceN}
/{source1},...,{sourceN}/{z}/{x}/{y}
Composite source TileJSON endpoint is available +at /{source1},...,{sourceN}, and tiles are available at /{source1},...,{sourceN}/{z}/{x}/{y}.
For example, composite source combining points and lines sources will be available at /points,lines/{z}/{x}/{y}
points
lines
/points,lines/{z}/{x}/{y}
# TileJSON +# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0 Sprite Sources -Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation. +Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation. API -Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately. +Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately. Sprite PNG -GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. +GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png. Sprite index -/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. +/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json. { "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another. +Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another. Configuring from CLI -A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file. -martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
# TileJSON curl localhost:3000/points,lines # Whole world as a single tile curl localhost:3000/points,lines/0/0/0
Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation.
icons/bicycle.svg
icons/bicycle
Given a directory with SVG images, Martin will generate a sprite – a JSON index and a PNG image, for both low and high +resolution displays. The SVG filenames without extension will be used as the sprite image IDs. The images are searched +recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs, +e.g. icons/bicycle.svg will be available as icons/bicycle sprite image. The sprite generation is not yet cached, and +may require external reverse proxy or CDN for faster operation.
Martin uses MapLibre sprites API specification to serve sprites via several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the changes will be reflected immediately.
Martin uses MapLibre sprites API specification to serve sprites via +several endpoints. The sprite image and index are generated on the fly, so if the sprite directory is updated, the +changes will be reflected immediately.
GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png.
GET /sprite/<sprite_id>.png
GET /sprite/<sprite_id>@2x.png
GET /sprite/<sprite_id>.png endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at GET /sprite/<sprite_id>@2x.png.
/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json.
/sprite/<sprite_id>.json
/sprite/<sprite_id>@2x.json
/sprite/<sprite_id>.json metadata index describing the position and size of each image inside the sprite. Just like +the PNG, there is a high DPI version available at /sprite/<sprite_id>@2x.json.
{ "bicycle": { "height": 15, @@ -981,13 +1156,19 @@ Sprite index
Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will override one another.
/sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>
Multiple sprite_id values can be combined into one sprite with the same pattern as for tile +joining: /sprite/<sprite_id1>,<sprite_id2>,...,<sprite_idN>. No ID renaming is done, so identical sprite names will +override one another.
A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the configuration to the config file.
--sprite
/sprite/sprite_a
/sprite/sprite_b
martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b +A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file. +martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b Configuring with Config File -A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured. +A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured. # Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
A sprite directory can be configured from the CLI with the --sprite flag. The flag can be used multiple times to +configure multiple sprite directories. The name of the sprite will be the name of the directory – in the example below, +the sprites will be available at /sprite/sprite_a and /sprite/sprite_b. Use --save-config to save the +configuration to the config file.
martin --sprite /path/to/sprite_a --sprite /path/to/other/sprite_b
A sprite directory can be configured from the config file with the sprite key, similar to how MBTiles and PMTiles are configured.
sprite
A sprite directory can be configured from the config file with the sprite key, similar to +how MBTiles and PMTiles are configured.
# Sprite configuration sprites: paths: @@ -998,17 +1179,22 @@ Font Sources -Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation. API -Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces. +Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces. Font Request Pattern/font/{name}/{start}-{end} Example/font/Overpass%20Mono%20Bold/0-255 Composite Font Request -When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph. +When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph. Composite Font Request with fallbacks Pattern/font/{name1},…,{nameN}/{start}-{end} Example/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255 @@ -1016,7 +1202,7 @@ Catalog Martin will show all available fonts at the /catalog endpoint. -curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID -In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc. +In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc. Reserved Source IDs -Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. +Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1. Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status. Catalog A list of all available sources is available via catalogue endpoint: -curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will generate them dynamically on the fly. +
otf
ttf
ttc
Martin can serve glyph ranges from otf, ttf, and ttc fonts as needed by MapLibre text rendering. Martin will +generate them dynamically on the fly. The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation.
Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font names as they usually contain spaces.
Fonts ranges are available either for a single font, or a combination of multiple fonts. The font names are +case-sensitive and should match the font name in the font file as published in the catalog. Make sure to URL-escape font +names as they usually contain spaces.
/font/{name}/{start}-{end}
/font/Overpass%20Mono%20Bold/0-255
When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the fonts contain the glyph.
When combining multiple fonts, the glyph range will contain glyphs from the first listed font if available, and fallback +to the next font if the glyph is not available in the first font, etc. The glyph range will be empty if none of the +fonts contain the glyph.
/font/{name1},…,{nameN}/{start}-{end}
/font/Overpass%20Mono%20Bold,Overpass%20Mono%20Light/0-255
Martin will show all available fonts at the /catalog endpoint.
/catalog
curl http://127.0.0.1:3000/catalog +curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog Using from CLI A font file or directory can be configured from the CLI with one or more --font parameters. -martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID
curl http://127.0.0.1:3000/catalog { "fonts": { "Overpass Mono Bold": { @@ -1045,7 +1231,7 @@ Catalog
A font file or directory can be configured from the CLI with one or more --font parameters.
--font
martin --font /path/to/font/file.ttf --font /path/to/font_dir +martin --font /path/to/font/file.ttf --font /path/to/font_dir Configuring from Config File A font directory can be configured from the config file with the fonts key. @@ -1071,14 +1257,17 @@ Duplicate Source ID
martin --font /path/to/font/file.ttf --font /path/to/font_dir
A font directory can be configured from the config file with the fonts key.
fonts
In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as /points, /points.1, etc.
/points
/points.1
In case there is more than one source that has the same name, e.g. a PG function is available in two +schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such +as /points, /points.1, etc.
Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1.
catalog
catalog.1
Some source IDs are reserved for internal use. If you try to use them, they will be automatically renamed to a unique ID +the same way as duplicate source IDs are handled, e.g. a catalog source will become catalog.1.
Some of the reserved IDs: _, catalog, config, font, health, help, index, manifest, metrics, refresh, reload, sprite, status.
_
config
font
health
help
index
manifest
metrics
refresh
reload
status
A list of all available sources is available via catalogue endpoint:
curl localhost:3000/catalog | jq +curl localhost:3000/catalog | jq { "tiles" { @@ -1115,8 +1304,9 @@ Catalog Source TileJSON All tile sources have a TileJSON endpoint available at the /{SourceID}. -For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint. -curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
curl localhost:3000/catalog | jq
{ "tiles" { @@ -1115,8 +1304,9 @@ Catalog
All tile sources have a TileJSON endpoint available at the /{SourceID}.
/{SourceID}
For example, a points function or a table will be available as /points. Composite source combining points and lines sources will be available at /points,lines endpoint.
/points,lines
curl localhost:3000/points | jq +For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint. +curl localhost:3000/points | jq curl localhost:3000/points,lines | jq Using with MapLibre @@ -1255,17 +1445,22 @@ Source TileJS
For example, a points function or a table will be available as /points. Composite source combining points +and lines sources will be available at /points,lines endpoint.
curl localhost:3000/points | jq curl localhost:3000/points,lines | jq
You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension
First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database
martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension
First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database
martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require
You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension
heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
heroku pg:psql -a APP_NAME -c 'create extension postgis'
Use the same environment variables as Heroku suggests for psql.
export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Use the same environment variables as +Heroku suggests for psql.
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 @@ -1273,7 +1468,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" CLI Tools Martin project contains additional tooling to help manage the data servable with Martin tile server. @@ -1285,11 +1480,17 @@ mbtiles This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page. The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets. Generating Tiles in Bulk -martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas (bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. -After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. This allows the MBTiles file to be validated using mbtiles validate command. +martin-cp is a tool for generating tiles in bulk, from any source(s) supported by Martin, and save retrieved tiles +into a new or an existing MBTiles file. martin-cp can be used to generate tiles for a large area or multiple areas ( +bounding boxes). If multiple areas overlap, it will ensure each tile is generated only once. martin-cp supports the +same configuration file and CLI arguments as Martin server, so it can support all sources and even combining sources. +After copying, martin-cp will update the agg_tiles_hash metadata value unless --skip-agg-tiles-hash is specified. +This allows the MBTiles file to be validated +using mbtiles validate command. Usage -This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. -martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca"
Martin project contains additional tooling to help manage the data servable with Martin tile server.
This tool can be installed by compiling the latest released version with cargo install mbtiles --locked, or by downloading a pre-built binary from the releases page.
cargo install mbtiles --locked
The mbtiles utility builds on top of the MBTiles specification. It adds a few additional conventions to ensure that the content of the tile data is valid, and can be used for reliable diffing and patching of the tilesets.
martin-cp --output-file tileset.mbtiles \ +This copies tiles from a PostGIS table my_table into an MBTiles file tileset.mbtiles +using normalized schema, with zoom levels from 0 to 10, and bounds of the whole world. +martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage MBTiles information and metadata summary -Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom level. The command will also print the bounding box of the covered area per zoom level. -MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ --min-zoom 0 \ @@ -1299,8 +1500,10 @@ Usage
MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles +Use mbtiles summary to get a summary of the contents of an MBTiles file. The command will print a table with the +number of tiles per zoom level, the size of the smallest and largest tiles, and the average size of tiles at each zoom +level. The command will also print the bounding box of the covered area per zoom level. +MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85 meta-all -Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not stable, and should only be used for visual inspection. -mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB Page size: 4.00KiB @@ -1317,16 +1520,19 @@ summary all | 196 | 64B | 1.0KiB | 96B | -180,-85,180,85
mbtiles meta-all my_file.mbtiles +Print all metadata values to stdout, as well as the results of tile detection. The format of the values printed is not +stable, and should only be used for visual inspection. +mbtiles meta-all my_file.mbtiles meta-get -Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get the description value from an mbtiles file: -mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles meta-get my_file.mbtiles description +Retrieve raw metadata value by its name. The value is printed to stdout without any modifications. For example, to get +the description value from an mbtiles file: +mbtiles meta-get my_file.mbtiles description meta-set -Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value to A vector tile dataset: -mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles meta-set my_file.mbtiles description "A vector tile dataset" +Set metadata value by its name, or delete the key if no value is supplied. For example, to set the description value +to A vector tile dataset: +mbtiles meta-set my_file.mbtiles description "A vector tile dataset" MBTiles Schemas The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file. @@ -1399,23 +1605,24 @@ normalized Copying, Diffing, and Patching MBTiles mbtiles copy Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
The mbtiles tool builds on top of the original MBTiles specification by specifying three different kinds of schema for tiles data: flat, flat-with-hash, and normalized. The mbtiles tool can convert between these schemas, and can also generate a diff between two files of any schemas, as well as merge multiple schema files into one file.
flat-with-hash
normalized
mbtiles copy src_file.mbtiles dst_file.mbtiles \ +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --min-zoom 0 --max-zoom 10 This command can also be used to generate files of different supported schema. -mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles copy normalized.mbtiles dst.mbtiles \ +mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash mbtiles copy --diff-with-file This option is identical to using mbtiles diff .... The following commands two are equivalent: -mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles +mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ --diff-with-file file2.mbtiles mbtiles copy --apply-patch -Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. -mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles copy src_file.mbtiles dst_file.mbtiles \ +Copy a source file to destination while also applying the diff file generated by copy --diff-with-file command above +to the destination mbtiles file. This allows safer application of the diff file, as the source file is not modified. +mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles Diffing MBTiles @@ -1429,7 +1636,7 @@ mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles diff< file to the original file, as the agg_tiles_hash value will be different after the diff is applied. The apply-patch command will automatically rename the agg_tiles_hash_after_apply value back to agg_tiles_hash when applying the diff. -# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. +# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
# This command will compare `file1.mbtiles` and `file2.mbtiles`, and generate a new diff file `diff.mbtiles`. mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles # If diff.mbtiles is applied to file1.mbtiles, it will produce file2.mbtiles @@ -1452,7 +1659,7 @@ Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Note that the agg_tiles_hash_after_apply metadata value will be renamed to agg_tiles_hash when applying the diff. This is done to avoid confusion when applying the diff file to the original file, as the agg_tiles_hash value will be different after the diff is applied. -mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
mbtiles apply-patch src_file.mbtiles diff_file.mbtiles +mbtiles apply-patch src_file.mbtiles diff_file.mbtiles Applying diff with SQLite Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@ sqlite3 src_file.mbtiles \ +sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@ MBTiles Validation -The original MBTiles specification does not provide any guarantees for the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure that the content of the tile data is valid performing several validation steps. If the file is not valid, the command will print an error message and exit with a non-zero exit code. -mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Another way to apply the diff is to use the sqlite3 command line tool directly. This SQL will delete all tiles @@ -1460,7 +1667,7 @@
sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ "ATTACH DATABASE @diffDbFilename AS diffDb;" \ @@ -1468,48 +1675,78 @@
mbtiles validate src_file.mbtiles +The original MBTiles specification does not provide any guarantees for +the content of the tile data in MBTiles. mbtiles validate assumes a few additional conventions and uses them to ensure +that the content of the tile data is valid performing several validation steps. If the file is not valid, the command +will print an error message and exit with a non-zero exit code. +mbtiles validate src_file.mbtiles SQLite Integrity check -The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default is quick. +The validate command will run PRAGMA integrity_check on the file, and will fail if the result is not ok. +The --integrity-check flag can be used to disable this check, or to make it more thorough with full value. Default +is quick. Schema check -The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. +The validate command will verify that the tiles table/view exists, and that it has the expected columns and indexes. +It will also verify that the metadata table/view exists, and that it has the expected columns and indexes. Per-tile validation -If the .mbtiles file uses flat_with_hash or normalized schema, the validate command will verify that the MD5 hash of the tile_data column matches the tile_hash or tile_id columns (depending on the schema). -A typical Normalized schema generated by tools like tilelive-copy use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. We also define a new flat-with-hash schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +If the .mbtiles file uses flat_with_hash +or normalized schema, the validate command will verify that the MD5 hash of +the tile_data column matches the tile_hash or tile_id columns (depending on the schema). +A typical Normalized schema generated by tools like tilelive-copy +use MD5 hash in the tile_id column. The Martin’s mbtiles tool can use this hash to verify the content of each tile. +We also define a new flat-with-hash schema that stores the hash and tile data in the +same table, allowing per-tile validation without the multiple table layout. Per-tile validation is not available for the flat schema, and will be skipped. Aggregate Content Validation -Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a new metadata value called agg_tiles_hash. -The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value is computed using the following SQL expression, which uses a custom md5_concat_hex function from sqlite-hashes crate: +Per-tile validation will catch individual tile corruption, but it will not detect overall datastore corruption such as +missing tiles, tiles that should not exist, or tiles with incorrect z/x/y values. For that, the mbtiles tool defines a +new metadata value called agg_tiles_hash. +The value is computed by hashing the combined value for all rows in the tiles table/view, ordered by z,x,y. The value +is computed using the following SQL expression, which uses a custom md5_concat_hex function +from sqlite-hashes crate: md5_concat_hex( CAST(zoom_level AS TEXT), CAST(tile_column AS TEXT), CAST(tile_row AS TEXT), tile_data) -In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will fail. -The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update to force the value to be updated, even if it is incorrect or does not exist. +In case there are no rows or all are NULL, the hash value of an empty string is used. Note that SQLite allows any value +type to be stored as in any column, so if tile_data accidentally contains non-blob/text/null value, validation will +fail. +The mbtiles tool will compute agg_tiles_hash value when copying or validating mbtiles files. Use --agg-hash update +to force the value to be updated, even if it is incorrect or does not exist. Development -Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest changes from the upstream repo. -git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
git clone https://github.com/maplibre/martin.git -o upstream +Clone Martin, setting remote name to upstream. This way main branch will be updated automatically with the latest +changes from the upstream repo. +git clone https://github.com/maplibre/martin.git -o upstream cd martin Fork Martin repo into your own GitHub account, and add your fork as a remote -git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
git remote add origin _URL_OF_YOUR_FORK_ +git remote add origin _URL_OF_YOUR_FORK_ Install docker and docker-compose -# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
# Ubuntu-based distros have an older version that might also work: +# Ubuntu-based distros have an older version that might also work: sudo apt install -y docker.io docker-compose Install a few required libs and tools: -# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
# For Ubuntu-based distros +# For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file -Install Just (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: -cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
cargo install just --locked +Install Just (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: +cargo install just --locked -When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. Run just to see all available commands. +When developing MBTiles SQL code, you may need to use just prepare-sqlite whenever SQL queries are modified. +Run just to see all available commands. +Martin as a library +Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features: + +postgres - enable PostgreSQL/PostGIS tile sources +pmtiles - enable PMTile tile sources +mbtiles - enable MBTile tile sources +fonts - enable font sources +sprites - enable sprite sources + diff --git a/quick-start-linux.html b/quick-start-linux.html new file mode 100644 index 000000000..e66691293 --- /dev/null +++ b/quick-start-linux.html @@ -0,0 +1,253 @@ + + + + + + On Linux - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Linux +mkdir martin +cd martin + +# Download some sample data +curl -O https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles + +# Download the latest version of Martin binary, extract it, and make it executable +curl -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 + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-macos.html b/quick-start-macos.html new file mode 100644 index 000000000..3117a026e --- /dev/null +++ b/quick-start-macos.html @@ -0,0 +1,265 @@ + + + + + + On macOS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on macOS + + +Download some demo tiles. + + +Download the latest version of Martin from +the release page. +Use about this Mac to find your processors type. + +Use martin-x86_64-apple-darwin.tar.gz for Intel +Use martin-aarch64-apple-darwin.tar.gz for M1 + + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-qgis.html b/quick-start-qgis.html new file mode 100644 index 000000000..c3b2b01b7 --- /dev/null +++ b/quick-start-qgis.html @@ -0,0 +1,265 @@ + + + + + + View with QGIS - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + View map with QGIS + + +Download, install, and run QGIS for your platform + + +Add a new Vector Tiles connection + + + + + +In the Vector Tile Connection dialog, give it some name and the URL of the Martin server, +e.g. http://localhost:3000/martin/{z}/{x}/{y}.pbf and click OK. + + + + + +In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click +on Add Layer to Project. + + + + + +The map should now be visible in the QGIS map view. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start-windows.html b/quick-start-windows.html new file mode 100644 index 000000000..24d874643 --- /dev/null +++ b/quick-start-windows.html @@ -0,0 +1,260 @@ + + + + + + On Windows - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Quick start on Windows + + +Download some demo tiles. + + +Download the latest Windows version of Martin from +the release page: martin-x86_64-pc-windows-msvc.zip + + +Extract content of both files and place them in a same directory. + + +Open the command prompt and navigate to the directory where martin and world_cities.mbtiles are located. + + +Run the following command to start Martin with the demo data: + + +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles + +View the map +See quick start with QGIS for instructions on how to view the map. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/quick-start.html b/quick-start.html new file mode 100644 index 000000000..ffe2c1e61 --- /dev/null +++ b/quick-start.html @@ -0,0 +1,240 @@ + + + + + + Quick Start - Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library + + + + + + + + + + + + + + + + + + + + + + + Light + Rust + Coal + Navy + Ayu + + + + + + + Martin Tile Server Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Martin Quick Start Guide +Choose your operating system to get started with Martin tile server + +Linux +macOS +Windows + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/recipes.html b/recipes.html index 1927b2627..2da575dcc 100644 --- a/recipes.html +++ b/recipes.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -181,17 +181,22 @@ Martin Tile Server Documentation Recipes Using with DigitalOcean PostgreSQL -You can use Martin with Managed PostgreSQL from DigitalOcean with PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the dashboard. After that, you can use the connection string and the CA certificate to connect to the database -martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" diff --git a/run-with-cli.html b/run-with-cli.html index f1dcb4320..de2d0729b 100644 --- a/run-with-cli.html +++ b/run-with-cli.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,7 +182,7 @@ Martin Tile Server Documentation Command-line Interface You can configure Martin using command-line interface. See martin --help or cargo run -- --help for more information. -Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
martin --ca-root-file ./ca-certificate.crt \ +You can use Martin +with Managed PostgreSQL from DigitalOcean with +PostGIS extension +First, you need to download the CA certificate and get your cluster connection string from +the dashboard. After that, you can use the connection string and the CA +certificate to connect to the database +martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require Using with Heroku PostgreSQL You can use Martin with Managed PostgreSQL from Heroku with PostGIS extension -heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca"
heroku pg:psql -a APP_NAME -c 'create extension postgis' +heroku pg:psql -a APP_NAME -c 'create extension postgis' -Use the same environment variables as Heroku suggests for psql. -export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca"
export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) +Use the same environment variables as +Heroku suggests for psql. +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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca"
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 @@ -199,7 +204,7 @@ export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" +export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca"
Usage: martin [OPTIONS] [CONNECTION]... +Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
Usage: martin [OPTIONS] [CONNECTION]... Arguments: [CONNECTION]... diff --git a/run-with-docker-compose.html b/run-with-docker-compose.html index 9e9ff3360..069fd5c47 100644 --- a/run-with-docker-compose.html +++ b/run-with-docker-compose.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -180,7 +180,8 @@ Martin Tile Server Documentation Running with Docker Compose -You can use example docker-compose.yml file as a reference +You can use example docker-compose.yml +file as a reference services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
services: martin: image: ghcr.io/maplibre/martin:v0.13.0 @@ -204,10 +205,10 @@ docker compose up -d db +docker compose up -d db Then, after db service is ready to accept connections, you can start martin -docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker compose up -d martin +docker compose up -d martin By default, Martin will be available at localhost:3000 diff --git a/run-with-docker.html b/run-with-docker.html index a13ea907a..1bf8bc20e 100644 --- a/run-with-docker.html +++ b/run-with-docker.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library @@ -182,36 +182,38 @@ Martin Tile Server Documentation Running with Docker You can use official Docker image ghcr.io/maplibre/martin Using Non-Local PostgreSQL -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ ghcr.io/maplibre/martin Exposing Local Files You can expose local files to the Docker container using the -v flag. -docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ +docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ ghcr.io/maplibre/martin /files Accessing Local PostgreSQL on Linux -If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container to access the localhost network. -For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports with -p because the container is already using the host network. -docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ +If you are running PostgreSQL instance on localhost, you have to change network settings to allow the Docker container +to access the localhost network. +For Linux, add the --net=host flag to access the localhost PostgreSQL service. You would not need to export ports +with -p because the container is already using the host network. +docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on macOS For macOS, use host.docker.internal as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ ghcr.io/maplibre/martin Accessing Local PostgreSQL on Windows For Windows, use docker.for.win.localhost as hostname to access the localhost PostgreSQL service. -docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ +docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface
docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ ghcr.io/maplibre/martin diff --git a/run-with-lambda.html b/run-with-lambda.html index 028c97b53..5e364c6d2 100644 --- a/run-with-lambda.html +++ b/run-with-lambda.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run-with-nginx.html b/run-with-nginx.html index 9fabfe42c..eadeb763a 100644 --- a/run-with-nginx.html +++ b/run-with-nginx.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface2.1.1. Environment Variables2.2. Running with Docker2.3. Running with Docker Compose2.4. Running with NGINX2.5. Running in AWS Lambda2.6. Troubleshooting3. Configuration File3.1. PostgreSQL Connections3.2. PostgreSQL Table Sources3.3. PostgreSQL Function Sources3.4. MBTiles and PMTiles File Sources3.5. Composite Sources3.6. Sprite Sources3.7. Font Sources4. Usage and Endpoint API4.1. Using with MapLibre4.2. Using with Leaflet4.3. Using with deck.gl4.4. Using with Mapbox4.5. Using with OpenLayers4.6. Recipes5. Tools5.1. martin-cp bulk tile generation5.2. MBTiles Metadata5.3. MBTiles Schemas5.4. Copying MBTiles5.5. Diffing/Patching MBTiles5.6. Validating MBTiles6. Development + Introduction1. Quick Start1.1. On Linux1.2. On macOS1.3. On Windows1.4. View with QGIS2. Installation3. Running3.1. Command Line Interface3.1.1. Environment Variables3.2. Running with Docker3.3. Running with Docker Compose3.4. Running with NGINX3.5. Running in AWS Lambda3.6. Troubleshooting4. Configuration File4.1. PostgreSQL Connections4.2. PostgreSQL Table Sources4.3. PostgreSQL Function Sources4.4. MBTiles and PMTiles File Sources4.5. Composite Sources4.6. Sprite Sources4.7. Font Sources5. Usage and Endpoint API5.1. Using with MapLibre5.2. Using with Leaflet5.3. Using with deck.gl5.4. Using with Mapbox5.5. Using with OpenLayers5.6. Recipes6. Tools6.1. martin-cp bulk tile generation6.2. MBTiles Metadata6.3. MBTiles Schemas6.4. Copying MBTiles6.5. Diffing/Patching MBTiles6.6. Validating MBTiles7. Development7.1. Martin as a library diff --git a/run.html b/run.html index 89ed51cc4..27c98ecb7 100644 --- a/run.html +++ b/run.html @@ -88,7 +88,7 @@ - Introduction1. Installation2. Running2.1. Command Line Interface