diff --git a/README.md b/README.md index bbcf8a5ff..47338b2f8 100755 --- a/README.md +++ b/README.md @@ -8,116 +8,27 @@ [![Security audit](https://github.com/maplibre/martin/workflows/Security%20audit/badge.svg)](https://github.com/maplibre/martin/security) [![CI build](https://github.com/maplibre/martin/actions/workflows/ci.yml/badge.svg)](https://github.com/maplibre/martin/actions) -Martin is a tile server able to generate and serve [vector tiles](https://github.com/mapbox/vector-tile-spec) on the fly from large [PostGIS](https://github.com/postgis/postgis) databases, [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) (local or remote), and [MBTile](https://github.com/mapbox/mbtiles-spec) files, allowing multiple tile sources to be dynamically combined into one. Martin optimizes for speed and heavy traffic, and is written in [Rust](https://github.com/rust-lang/rust). - -Additionally, there are [several tools](https://maplibre.org/martin/tools.html) for generating tiles in bulk from any Martin-supported sources (similar to `tilelive-copy`), copying tiles between MBTiles files, creating deltas (patches) and applying them, and validating MBTiles files. - -See [Martin book](https://maplibre.org/martin/) for complete documentation. - -## Installation - -_See [installation instructions](https://maplibre.org/martin/installation.html) in the Martin book._ - -**Prerequisites:** If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. - -You can download martin from [GitHub releases page](https://github.com/maplibre/martin/releases). - -| Platform | AMD-64 | ARM-64 | -|----------|--------------------------------------------------------------------------------------------------|-------------------------------------| -| Linux | [.tar.gz][rl-linux-x64] (gnu)
[.tar.gz][rl-linux-x64-musl] (musl)
[.deb][rl-linux-x64-deb] | [.tar.gz][rl-linux-a64-musl] (musl) | -| macOS | [.tar.gz][rl-macos-x64] | [.tar.gz][rl-macos-a64] | -| Windows | [.zip][rl-win64-zip] | | - -[rl-linux-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz -[rl-linux-x64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-musl.tar.gz -[rl-linux-x64-deb]: https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb -[rl-linux-a64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-unknown-linux-musl.tar.gz -[rl-macos-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz -[rl-macos-a64]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-apple-darwin.tar.gz -[rl-win64-zip]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip - -If you are using macOS and [Homebrew](https://brew.sh/) you can install `martin` and `mbtiles` using Homebrew tap. - -```shell -brew tap maplibre/martin -brew install martin -``` - -## Running Martin Service - -_See [running instructions](https://maplibre.org/martin/run.html) in the Martin book._ - -Martin supports any number of PostgreSQL/PostGIS database connections with [geospatial-enabled](https://postgis.net/docs/using_postgis_dbmanagement.html#geometry_columns) tables and tile-producing SQL functions, as well as [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) and [MBTile](https://github.com/mapbox/mbtiles-spec) files as tile sources. - -Martin can auto-discover tables and functions using a [connection string](https://maplibre.org/martin/pg-connections.html). A PG connection string can also be passed via the `DATABASE_URL` environment variable. - -Each tile source will have a [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint. - -#### Examples - -```shell -# publish all tables and functions from a single database -export DATABASE_URL="postgresql://user:password@host:port/database" -martin - -# same as above, but passing connection string via CLI, together with a directory of .mbtiles/.pmtiles files -martin postgresql://user:password@host:port/database path/to/dir - -# publish all discovered tables/funcs from two DBs -# and generate config file with all detected sources -martin postgres://... postgres://... --save-config config.yaml - -# use configuration file instead of auto-discovery -martin --config config.yaml -``` - -#### Docker Example - -_See [Docker instructions](https://maplibre.org/martin/run-with-docker.html) in the Martin book._ - -Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). 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. - -```shell -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 -``` - -## API - -_See [API documentation](https://maplibre.org/martin/using.html) in the Martin book._ - -Martin data is available via the HTTP `GET` endpoints: - -| URL | Description | -|-----------------------------------------|-----------------------------------------------| -| `/` | Status text, that will eventually show web UI | -| `/catalog` | List of all sources | -| `/{sourceID}` | Source TileJSON | -| `/{sourceID}/{z}/{x}/{y}` | Map Tiles | -| `/{source1},…,{sourceN}` | Composite Source TileJSON | -| `/{source1},…,{sourceN}/{z}/{x}/{y}` | Composite Source Tiles | -| `/sprite/{spriteID}[@2x].{json,png}` | Sprites (low and high DPI, index/png) | -| `/font/{font}/{start}-{end}` | Font source | -| `/font/{font1},…,{fontN}/{start}-{end}` | Composite Font source | -| `/health` | Martin server health check: returns 200 `OK` | - -## Re-use 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 - -## Documentation - -See [Martin book](https://maplibre.org/martin/) for complete documentation. +Martin is a tile server able to generate and serve [vector tiles](https://github.com/mapbox/vector-tile-spec) on the fly +from large [PostGIS](https://github.com/postgis/postgis) +databases, [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) (local or remote), +and [MBTile](https://github.com/mapbox/mbtiles-spec) files, allowing multiple tile sources to be dynamically combined +into one. Martin optimizes for speed and heavy traffic, and is written in [Rust](https://github.com/rust-lang/rust). + +### Features + +* Serve vector tiles from PostGIS, PMTile, and MBTile sources +* [Combine](https://maplibre.org/martin/sources-composite.html) multiple tile sources +* Generate [sprites](https://maplibre.org/martin/sources-sprites.html) and [font glyphs](https://maplibre.org/martin/sources-fonts.html) +* Generate tiles in bulk from any Martin-supported sources into an `.mbtiles` file with [martin-cp](https://maplibre.org/martin/martin-cp.html) tool +* Examine, copy, validate, compare, and apply diffs between `.mbtiles` files with [mbtiles](https://maplibre.org/martin/tools.html#mbtiles) tool + +### Documentation + +* [Quick Start](https://maplibre.org/martin/quick-start.html) +* [Installation](https://maplibre.org/martin/installation.html) +* Running with [CLI](https://maplibre.org/martin/run-with-cli.html) + or [configuration file](https://maplibre.org/martin/config-file.html) +* [Usage and API](https://maplibre.org/martin/using.html) ## License diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index ac0d5e000..62b84d8f8 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,5 +1,10 @@ [Introduction](introduction.md) +- [Quick Start](quick-start.md) + - [On Linux](quick-start-linux.md) + - [On macOS](quick-start-macos.md) + - [On Windows](quick-start-windows.md) + - [View with QGIS](quick-start-qgis.md) - [Installation](installation.md) - [Running](run.md) - [Command Line Interface](run-with-cli.md) @@ -32,3 +37,4 @@ - [Diffing/Patching MBTiles](mbtiles-diff.md) - [Validating MBTiles](mbtiles-validation.md) - [Development](development.md) + - [Martin as a library](martin-as-a-library.md) diff --git a/docs/src/config-file.md b/docs/src/config-file.md index ad930a947..2468893a4 100644 --- a/docs/src/config-file.md +++ b/docs/src/config-file.md @@ -6,14 +6,14 @@ contain environment variables, which will be expanded before parsing. For exampl config file: `connection_string: ${MY_DATABASE_URL}`, or with a default `connection_string: ${MY_DATABASE_URL:-postgresql://postgres@localhost/db}` -```shell +```bash 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. -```shell +```bash martin ... ... ... --save-config config.yaml ``` diff --git a/docs/src/development.md b/docs/src/development.md index b3bc71147..ad0369cc2 100644 --- a/docs/src/development.md +++ b/docs/src/development.md @@ -1,36 +1,39 @@ # Development -Clone Martin, setting remote name to `upstream`. This way `main` branch will be updated automatically with the latest changes from the upstream repo. +Clone Martin, setting remote name to `upstream`. This way `main` branch will be updated automatically with the latest +changes from the upstream repo. -```shell, ignore +```bash, ignore 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 -```shell, ignore +```bash, ignore git remote add origin _URL_OF_YOUR_FORK_ ``` Install [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/) -```shell, ignore +```bash, ignore # 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: -```shell, ignore +```bash, ignore # For Ubuntu-based distros sudo apt install -y build-essential pkg-config jq file ``` -Install [Just](https://github.com/casey/just#readme) (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source: +Install [Just](https://github.com/casey/just#readme) (improved makefile processor). Note that some Linux and Homebrew +distros have outdated versions of Just, so you should install it from source: -```shell, ignore +```bash, ignore 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. diff --git a/docs/src/images/qgis_add_to_layers.png b/docs/src/images/qgis_add_to_layers.png new file mode 100644 index 000000000..68d6097a9 Binary files /dev/null and b/docs/src/images/qgis_add_to_layers.png differ diff --git a/docs/src/images/qgis_add_vector_tile.png b/docs/src/images/qgis_add_vector_tile.png new file mode 100644 index 000000000..de707e506 Binary files /dev/null and b/docs/src/images/qgis_add_vector_tile.png differ diff --git a/docs/src/images/qgis_add_vector_tile_options.png b/docs/src/images/qgis_add_vector_tile_options.png new file mode 100644 index 000000000..2b912926d Binary files /dev/null and b/docs/src/images/qgis_add_vector_tile_options.png differ diff --git a/docs/src/images/qgis_shows_in_the_map.png b/docs/src/images/qgis_shows_in_the_map.png new file mode 100644 index 000000000..84816fe9f Binary files /dev/null and b/docs/src/images/qgis_shows_in_the_map.png differ diff --git a/docs/src/installation.md b/docs/src/installation.md index 70d6b289f..472a80d92 100644 --- a/docs/src/installation.md +++ b/docs/src/installation.md @@ -1,48 +1,85 @@ ### Prerequisites -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. -### Binary Distributions +### Docker + +Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). 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. + +```bash +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](https://github.com/maplibre/martin/releases). -| Platform | Downloads (latest) | -|----------|------------------------| -| Linux | [64-bit][rl-linux-tar] | -| macOS | [64-bit][rl-macos-tar] | -| Windows | [64-bit][rl-win64-zip] | +| Platform | x64 | ARM-64 | +|----------|--------------------------------------------------------------------------------------------------|-------------------------------------| +| Linux | [.tar.gz][rl-linux-x64] (gnu)
[.tar.gz][rl-linux-x64-musl] (musl)
[.deb][rl-linux-x64-deb] | [.tar.gz][rl-linux-a64-musl] (musl) | +| macOS | [.tar.gz][rl-macos-x64] | [.tar.gz][rl-macos-a64] | +| Windows | [.zip][rl-win64-zip] | | -[rl-linux-tar]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz -[rl-macos-tar]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz -[rl-win64-zip]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip +[rl-linux-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-gnu.tar.gz -### Building with Cargo +[rl-linux-x64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-unknown-linux-musl.tar.gz -If you [install Rust](https://www.rust-lang.org/tools/install), you can build martin from source with Cargo: +[rl-linux-x64-deb]: https://github.com/maplibre/martin/releases/latest/download/martin-Debian-x86_64.deb -```shell -cargo install martin --locked +[rl-linux-a64-musl]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-unknown-linux-musl.tar.gz + +[rl-macos-x64]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz + +[rl-macos-a64]: https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-apple-darwin.tar.gz + +[rl-win64-zip]: https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip + +Rust users can install pre-built martin binary +with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) and `cargo`. + +```bash +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](https://github.com/maplibre/martin/issues/578). + +#### Homebrew If you are using macOS and [Homebrew](https://brew.sh/) you can install martin using Homebrew tap. -```shell +```bash brew tap maplibre/martin brew install martin +martin --help ``` -### Docker +#### Debian Packages(x86_64) manually -Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). 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. +```bash +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 +``` -```shell -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 +### Building From source + +If you [install Rust](https://www.rust-lang.org/tools/install), you can build martin from source with Cargo: + +```bash +cargo install martin --locked +martin --help ``` diff --git a/docs/src/martin-as-a-library.md b/docs/src/martin-as-a-library.md new file mode 100644 index 000000000..680d2435e --- /dev/null +++ b/docs/src/martin-as-a-library.md @@ -0,0 +1,9 @@ +# 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/docs/src/martin-cp.md b/docs/src/martin-cp.md index 53e06b319..38660598b 100644 --- a/docs/src/martin-cp.md +++ b/docs/src/martin-cp.md @@ -1,14 +1,20 @@ # 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. +`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](./mbtiles-validation.md#aggregate-content-validation) using `mbtiles validate` command. +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](./mbtiles-validation.md#aggregate-content-validation) +using `mbtiles validate` command. ## Usage -This copies tiles from a PostGIS table `my_table` into an MBTiles file `tileset.mbtiles` using [normalized](mbtiles-schema.md) schema, with zoom levels from 0 to 10, and bounds of the whole world. +This copies tiles from a PostGIS table `my_table` into an MBTiles file `tileset.mbtiles` +using [normalized](mbtiles-schema.md) schema, with zoom levels from 0 to 10, and bounds of the whole world. -```shell +```bash martin-cp --output-file tileset.mbtiles \ --mbtiles-type normalized \ "--bbox=-180,-90,180,90" \ diff --git a/docs/src/mbtiles-copy.md b/docs/src/mbtiles-copy.md index 29a3a46a6..7b005b1bc 100644 --- a/docs/src/mbtiles-copy.md +++ b/docs/src/mbtiles-copy.md @@ -4,14 +4,14 @@ Copy command copies an mbtiles file, optionally filtering its content by zoom levels. -```shell +```bash 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-schema.md). -```shell +```bash mbtiles copy normalized.mbtiles dst.mbtiles \ --dst-mbttype flat-with-hash ``` @@ -20,7 +20,7 @@ mbtiles copy normalized.mbtiles dst.mbtiles \ This option is identical to using [`mbtiles diff ...`](mbtiles-diff.md). The following commands two are equivalent: -```shell +```bash mbtiles diff file1.mbtiles file2.mbtiles diff.mbtiles mbtiles copy file1.mbtiles diff.mbtiles \ @@ -29,9 +29,10 @@ mbtiles copy file1.mbtiles diff.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 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. -```shell +```bash mbtiles copy src_file.mbtiles dst_file.mbtiles \ --apply-patch diff.mbtiles ``` diff --git a/docs/src/mbtiles-diff.md b/docs/src/mbtiles-diff.md index b2d627b2d..d5a02e2e8 100644 --- a/docs/src/mbtiles-diff.md +++ b/docs/src/mbtiles-diff.md @@ -13,7 +13,7 @@ file to the original file, as the `agg_tiles_hash` value will be different after command will automatically rename the `agg_tiles_hash_after_apply` value back to `agg_tiles_hash` when applying the diff. -```shell +```bash # 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 @@ -41,7 +41,7 @@ Note that the `agg_tiles_hash_after_apply` metadata value will be renamed to `ag 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. -```shell +```bash mbtiles apply-patch src_file.mbtiles diff_file.mbtiles ``` @@ -53,7 +53,7 @@ from `diff_file.mbtiles` into `src_file.mbtiles`, where both files are of `flat` passed as a query parameter to the sqlite3 command line tool, and then used in the SQL statements. Note that this does not update the `agg_tiles_hash` metadata value, so it will be incorrect after the diff is applied. -```shell +```bash sqlite3 src_file.mbtiles \ -bail \ -cmd ".parameter set @diffDbFilename diff_file.mbtiles" \ diff --git a/docs/src/mbtiles-meta.md b/docs/src/mbtiles-meta.md index ac1d0fb76..422cf51e8 100644 --- a/docs/src/mbtiles-meta.md +++ b/docs/src/mbtiles-meta.md @@ -2,9 +2,11 @@ ## 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. +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. -```shell +```bash MBTiles file summary for tests/fixtures/mbtiles/world_cities.mbtiles Schema: flat File size: 48.00KiB @@ -24,24 +26,27 @@ Page count: 12 ## 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. +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. -```shell +```bash 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: +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: -```shell +```bash 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`: +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`: -```shell +```bash mbtiles meta-set my_file.mbtiles description "A vector tile dataset" ``` diff --git a/docs/src/mbtiles-validation.md b/docs/src/mbtiles-validation.md index bd5486c5e..4e95930b5 100644 --- a/docs/src/mbtiles-validation.md +++ b/docs/src/mbtiles-validation.md @@ -1,32 +1,47 @@ # MBTiles Validation -The original [MBTiles specification](https://github.com/mapbox/mbtiles-spec#readme) 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. +The original [MBTiles specification](https://github.com/mapbox/mbtiles-spec#readme) 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. -```shell +```bash 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](mbtiles-schema.md#flat-with-hash) or [normalized](mbtiles-schema.md#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). +If the `.mbtiles` file uses [flat_with_hash](mbtiles-schema.md#flat-with-hash) +or [normalized](mbtiles-schema.md#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](https://github.com/mapbox/TileLive#bintilelive-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](mbtiles-schema.md#flat-with-hash) schema that stores the hash and tile data in the same table, allowing per-tile validation without the multiple table layout. +A typical Normalized schema generated by tools like [tilelive-copy](https://github.com/mapbox/TileLive#bintilelive-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](mbtiles-schema.md#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`. +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](https://crates.io/crates/sqlite-hashes): +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](https://crates.io/crates/sqlite-hashes): ```sql, ignore md5_concat_hex( @@ -36,6 +51,9 @@ md5_concat_hex( 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. +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 `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/docs/src/quick-start-linux.md b/docs/src/quick-start-linux.md new file mode 100644 index 000000000..093b323b0 --- /dev/null +++ b/docs/src/quick-start-linux.md @@ -0,0 +1,24 @@ +## Quick start on Linux + +```bash +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](quick-start-qgis.md) for instructions on how to view the map. diff --git a/docs/src/quick-start-macos.md b/docs/src/quick-start-macos.md new file mode 100644 index 000000000..921e8a2f4 --- /dev/null +++ b/docs/src/quick-start-macos.md @@ -0,0 +1,27 @@ +## Quick start on macOS + +1. Download some [demo tiles](https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles). + +2. Download the latest version of Martin from + the [release page](https://github.com/maplibre/martin/releases/latest/download). + Use [about this Mac](https://support.apple.com/en-us/116943) to find your processors type. + * Use [martin-x86_64-apple-darwin.tar.gz](https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-apple-darwin.tar.gz) for Intel + * Use [martin-aarch64-apple-darwin.tar.gz](https://github.com/maplibre/martin/releases/latest/download/martin-aarch64-apple-darwin.tar.gz) for M1 + +3. Extract content of both files and place them in a same directory. + +4. Open the command prompt and navigate to the directory where `martin` and `world_cities.mbtiles` are located. + +5. Run the following command to start Martin with the demo data: + +```bash +# Show Martin help screen +./martin --help + +# Run Martin with the sample data as the only tile source +./martin world_cities.mbtiles +``` + +### View the map + +See [quick start with QGIS](quick-start-qgis.md) for instructions on how to view the map. diff --git a/docs/src/quick-start-qgis.md b/docs/src/quick-start-qgis.md new file mode 100644 index 000000000..8ad2db54b --- /dev/null +++ b/docs/src/quick-start-qgis.md @@ -0,0 +1,17 @@ +### View map with QGIS + +1. Download, install, and run [QGIS](https://qgis.org/en/site/forusers/download.html) for your platform + +2. Add a new `Vector Tiles` connection + > ![alt text](images/qgis_add_vector_tile.png) + +3. 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`. + > ![alt text](images/qgis_add_vector_tile_options.png) + +4. In the QGIS browser panel (left), double-click the newly added connection, or right-click it and click + on `Add Layer to Project`. + > ![alt text](images/qgis_add_to_layers.png) + +5. The map should now be visible in the QGIS map view. + > ![alt text](images/qgis_shows_in_the_map.png) diff --git a/docs/src/quick-start-windows.md b/docs/src/quick-start-windows.md new file mode 100644 index 000000000..af7fa0f5e --- /dev/null +++ b/docs/src/quick-start-windows.md @@ -0,0 +1,24 @@ +## Quick start on Windows + +1. Download some [demo tiles](https://github.com/maplibre/martin/blob/main/tests/fixtures/mbtiles/world_cities.mbtiles). + +2. Download the latest Windows version of Martin from + the [release page](https://github.com/maplibre/martin/releases): []([martin-x86_64-pc-windows-msvc.zip](https://github.com/maplibre/martin/releases/latest/download/martin-x86_64-pc-windows-msvc.zip) + +3. Extract content of both files and place them in a same directory. + +4. Open the command prompt and navigate to the directory where `martin` and `world_cities.mbtiles` are located. + +5. Run the following command to start Martin with the demo data: + +```bash +# Show Martin help screen +martin --help + +# Run Martin with the sample data as the only tile source +martin world_cities.mbtiles +``` + +### View the map + +See [quick start with QGIS](quick-start-qgis.md) for instructions on how to view the map. diff --git a/docs/src/quick-start.md b/docs/src/quick-start.md new file mode 100644 index 000000000..5e35ee51f --- /dev/null +++ b/docs/src/quick-start.md @@ -0,0 +1,7 @@ +## Martin Quick Start Guide + +Choose your operating system to get started with Martin tile server + +* [Linux](quick-start-linux.md) +* [macOS](quick-start-macos.md) +* [Windows](quick-start-windows.md) diff --git a/docs/src/recipes.md b/docs/src/recipes.md index 2c864efeb..423c64b08 100644 --- a/docs/src/recipes.md +++ b/docs/src/recipes.md @@ -2,11 +2,15 @@ ### Using with DigitalOcean PostgreSQL -You can use Martin with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with PostGIS extension +You can use Martin +with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with +PostGIS extension -First, you need to download the CA certificate and get your cluster connection string from the [dashboard](https://cloud.digitalocean.com/databases). After that, you can use the connection string and the CA certificate to connect to the database +First, you need to download the CA certificate and get your cluster connection string from +the [dashboard](https://cloud.digitalocean.com/databases). After that, you can use the connection string and the CA +certificate to connect to the database -```shell +```bash martin --ca-root-file ./ca-certificate.crt \ postgresql://user:password@host:port/db?sslmode=require ``` @@ -15,13 +19,14 @@ martin --ca-root-file ./ca-certificate.crt \ You can use Martin with [Managed PostgreSQL from Heroku](https://www.heroku.com/postgres) with PostGIS extension -```shell +```bash heroku pg:psql -a APP_NAME -c 'create extension postgis' ``` -Use the same environment variables as Heroku [suggests for psql](https://devcenter.heroku.com/articles/heroku-postgres-via-mtls#step-2-configure-environment-variables). +Use the same environment variables as +Heroku [suggests for psql](https://devcenter.heroku.com/articles/heroku-postgres-via-mtls#step-2-configure-environment-variables). -```shell +```bash export DATABASE_URL=$(heroku config:get DATABASE_URL -a APP_NAME) export PGSSLCERT=DIRECTORY/PREFIXpostgresql.crt export PGSSLKEY=DIRECTORY/PREFIXpostgresql.key @@ -32,6 +37,6 @@ martin You may also be able to validate SSL certificate with an explicit sslmode, e.g. -```shell +```bash export DATABASE_URL="$(heroku config:get DATABASE_URL -a APP_NAME)?sslmode=verify-ca" ``` diff --git a/docs/src/run-with-cli.md b/docs/src/run-with-cli.md index 17b16fbaf..fe6ddaf14 100644 --- a/docs/src/run-with-cli.md +++ b/docs/src/run-with-cli.md @@ -3,7 +3,7 @@ You can configure Martin using command-line interface. See `martin --help` or `cargo run -- --help` for more information. -```shell +```text Usage: martin [OPTIONS] [CONNECTION]... Arguments: diff --git a/docs/src/run-with-docker-compose.md b/docs/src/run-with-docker-compose.md index 005f0187e..31a6cd2a6 100644 --- a/docs/src/run-with-docker-compose.md +++ b/docs/src/run-with-docker-compose.md @@ -1,6 +1,7 @@ ## Running with Docker Compose -You can use example [`docker-compose.yml`](https://raw.githubusercontent.com/maplibre/martin/main/docker-compose.yml) file as a reference +You can use example [`docker-compose.yml`](https://raw.githubusercontent.com/maplibre/martin/main/docker-compose.yml) +file as a reference ```yml services: @@ -28,13 +29,13 @@ services: First, you need to start `db` service -```shell +```bash docker compose up -d db ``` Then, after `db` service is ready to accept connections, you can start `martin` -```shell +```bash docker compose up -d martin ``` diff --git a/docs/src/run-with-docker.md b/docs/src/run-with-docker.md index 75ae7e488..ebb5b5421 100644 --- a/docs/src/run-with-docker.md +++ b/docs/src/run-with-docker.md @@ -4,7 +4,7 @@ You can use official Docker image [`ghcr.io/maplibre/martin`](https://ghcr.io/ma ### Using Non-Local PostgreSQL -```shell +```bash docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@postgres.example.org/db \ @@ -15,7 +15,7 @@ docker run \ You can expose local files to the Docker container using the `-v` flag. -```shell +```bash docker run \ -p 3000:3000 \ -v /path/to/local/files:/files \ @@ -24,11 +24,13 @@ docker run \ ### 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. +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. +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. -```shell +```bash docker run \ --net=host \ -e DATABASE_URL=postgresql://postgres@localhost/db \ @@ -39,7 +41,7 @@ docker run \ For macOS, use `host.docker.internal` as hostname to access the `localhost` PostgreSQL service. -```shell +```bash docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@host.docker.internal/db \ @@ -50,7 +52,7 @@ docker run \ For Windows, use `docker.for.win.localhost` as hostname to access the `localhost` PostgreSQL service. -```shell +```bash docker run \ -p 3000:3000 \ -e DATABASE_URL=postgresql://postgres@docker.for.win.localhost/db \ diff --git a/docs/src/run.md b/docs/src/run.md index 4007b4cd0..829fa1323 100644 --- a/docs/src/run.md +++ b/docs/src/run.md @@ -1,9 +1,12 @@ # Usage -Martin requires at least one PostgreSQL [connection string](pg-connections.md) or a [tile source file](sources-files.md) as a command-line argument. A PG connection string can also be passed via the `DATABASE_URL` environment variable. +Martin requires at least one PostgreSQL [connection string](pg-connections.md) or a [tile source file](sources-files.md) +as a command-line argument. A PG connection string can also be passed via the `DATABASE_URL` environment variable. -```shell +```bash martin postgresql://postgres@localhost/db ``` -Martin provides [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint for each [geospatial-enabled](https://postgis.net/docs/using_postgis_dbmanagement.html#geometry_columns) table in your database. +Martin provides [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint for +each [geospatial-enabled](https://postgis.net/docs/using_postgis_dbmanagement.html#geometry_columns) table in your +database. diff --git a/docs/src/sources-composite.md b/docs/src/sources-composite.md index 255b5caf0..68769b470 100644 --- a/docs/src/sources-composite.md +++ b/docs/src/sources-composite.md @@ -1,14 +1,16 @@ ## 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](https://github.com/mapbox/tilejson-spec) endpoint is available at `/{source1},...,{sourceN}`, and tiles are available at `/{source1},...,{sourceN}/{z}/{x}/{y}`. +Composite source [TileJSON](https://github.com/mapbox/tilejson-spec) 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}` -```shell +```bash # TileJSON curl localhost:3000/points,lines diff --git a/docs/src/sources-files.md b/docs/src/sources-files.md index 658453c2e..c755794f5 100644 --- a/docs/src/sources-files.md +++ b/docs/src/sources-files.md @@ -1,9 +1,12 @@ ## MBTiles and PMTiles File Sources -Martin can serve any type of tiles from [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) and [MBTile](https://github.com/mapbox/mbtiles-spec) 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 can serve any type of tiles from [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) +and [MBTile](https://github.com/mapbox/mbtiles-spec) 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: -```shell +```bash martin /path/to/mbtiles/file.mbtiles /path/to/directory https://example.org/path/tiles.pmtiles ``` -You may also want to generate a [config file](config-file.md) 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](config-file.md) using the `--save-config my-config.yaml`, and later edit +it and use it with `--config my-config.yaml` option. diff --git a/docs/src/sources-fonts.md b/docs/src/sources-fonts.md index 21095ca8e..a223eb06e 100644 --- a/docs/src/sources-fonts.md +++ b/docs/src/sources-fonts.md @@ -1,11 +1,14 @@ ## 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 | |---------|--------------------------------------| @@ -14,7 +17,9 @@ Fonts ranges are available either for a single font, or a combination of multipl ### 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 | |---------|--------------------------------------------------------------| @@ -25,7 +30,7 @@ When combining multiple fonts, the glyph range will contain glyphs from the firs Martin will show all available fonts at the `/catalog` endpoint. -```shell +```bash curl http://127.0.0.1:3000/catalog { "fonts": { @@ -58,7 +63,7 @@ curl http://127.0.0.1:3000/catalog A font file or directory can be configured from the [CLI](run-with-cli.md) with one or more `--font` parameters. -```shell +```bash martin --font /path/to/font/file.ttf --font /path/to/font_dir ``` diff --git a/docs/src/sources-pg-functions.md b/docs/src/sources-pg-functions.md index 1dfa95536..3578c6ebb 100644 --- a/docs/src/sources-pg-functions.md +++ b/docs/src/sources-pg-functions.md @@ -1,6 +1,11 @@ ## PostgreSQL Function Sources -Function Source is a database function which can be used to query [vector tiles](https://github.com/mapbox/vector-tile-spec). 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](https://github.com/mapbox/vector-tile-spec). 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). | Argument | Type | Description | |----------------------------|---------|-------------------------| @@ -11,7 +16,8 @@ Function Source is a database function which can be used to query [vector tiles] ### 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: ```sql, ignore CREATE OR REPLACE @@ -63,15 +69,18 @@ END $$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE; ``` -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. +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. -```shell +```bash curl localhost:3000/function_zxy_query/0/0/0?token=martin ``` -You can also use [urlencoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) params to encode complex values: +You can also +use [urlencoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) +params to encode complex values: -```shell +```bash curl \ --data-urlencode 'arrayParam=[1, 2, 3]' \ --data-urlencode 'numberParam=42' \ @@ -101,7 +110,11 @@ You can access this params using [json operators](https://www.postgresql.org/doc ### Modifying TileJSON -Martin will automatically generate a basic [TileJSON](https://github.com/mapbox/tilejson-spec) 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](https://github.com/mapbox/tilejson-spec) 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): ```json { @@ -116,9 +129,12 @@ Martin will automatically generate a basic [TileJSON](https://github.com/mapbox/ #### 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](https://www.rfc-editor.org/rfc/rfc7386). The following example adds `attribution` and `version` fields to the `TileJSON`. +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](https://www.rfc-editor.org/rfc/rfc7386). +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. +**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. ```sql DO $do$ BEGIN diff --git a/docs/src/sources-sprites.md b/docs/src/sources-sprites.md index 809e87092..298b011ea 100644 --- a/docs/src/sources-sprites.md +++ b/docs/src/sources-sprites.md @@ -1,20 +1,28 @@ ## 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](https://maplibre.org/maplibre-style-spec/sprite/) 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](https://maplibre.org/maplibre-style-spec/sprite/) 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 ![sprite](sources-sprites.png) -`GET /sprite/.png` endpoint contains a single PNG sprite image that combines all sources images. Additionally, there is a high DPI version available at `GET /sprite/@2x.png`. +`GET /sprite/.png` endpoint contains a single PNG sprite image that combines all sources images. +Additionally, there is a high DPI version available at `GET /sprite/@2x.png`. ##### Sprite index -`/sprite/.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/@2x.json`. +`/sprite/.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/@2x.json`. ```json { @@ -31,19 +39,25 @@ Martin uses [MapLibre sprites API](https://maplibre.org/maplibre-style-spec/spri #### Combining Multiple Sprites -Multiple sprite_id values can be combined into one sprite with the same pattern as for tile joining: `/sprite/,,...,`. 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/,,...,`. 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. +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. -```shell +```bash 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](config-file.md) are configured. +A sprite directory can be configured from the config file with the `sprite` key, similar to +how [MBTiles and PMTiles](config-file.md) are configured. ```yaml # Sprite configuration diff --git a/docs/src/troubleshooting.md b/docs/src/troubleshooting.md index 0c46f4478..9800c2df8 100644 --- a/docs/src/troubleshooting.md +++ b/docs/src/troubleshooting.md @@ -1,17 +1,20 @@ ## 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: -```shell +```bash 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: +While this will only enable verbose logging for the `actix_web` module and enable debug logging for the `martin` +and `tokio_postgres` modules: -```shell +```bash export RUST_LOG=actix_web=info,martin=debug,tokio_postgres=debug martin postgresql://postgres@localhost/db ``` diff --git a/docs/src/using.md b/docs/src/using.md index 2d854b23f..2d8c3c537 100644 --- a/docs/src/using.md +++ b/docs/src/using.md @@ -17,11 +17,14 @@ Martin data is available via the HTTP `GET` endpoints: ### 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`. @@ -30,7 +33,7 @@ Some of the reserved IDs: `_`, `catalog`, `config`, `font`, `health`, `help`, `i A list of all available sources is available via catalogue endpoint: -```shell +```bash curl localhost:3000/catalog | jq ``` @@ -73,9 +76,10 @@ curl localhost:3000/catalog | jq All tile sources have a [TileJSON](https://github.com/mapbox/tilejson-spec) 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. +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. -```shell +```bash curl localhost:3000/points | jq curl localhost:3000/points,lines | jq ```