From 5d87b086feb587f6d3dfe95e14cf16635a6efa45 Mon Sep 17 00:00:00 2001 From: Yuri Astrakhan Date: Thu, 1 Jun 2023 16:15:05 -0400 Subject: [PATCH] improving readme/docs --- README.md | 45 ++++++++++++++++++++------------------------- docs/src/API.md | 20 ++++++++++---------- 2 files changed, 30 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 2aace99d..bd528bce 100755 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![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/workflows/CI/badge.svg)](https://github.com/maplibre/martin/actions) -Martin is a tile server able to generate [vector tiles](https://github.com/mapbox/vector-tile-spec) on the fly from large [PostGIS](https://github.com/postgis/postgis) databases, or serve tiles from [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) and [MBTile](https://github.com/mapbox/mbtiles-spec) files. Martin optimizes for speed and heavy traffic, and is written in [Rust](https://github.com/rust-lang/rust). +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), 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). See [Martin book](https://maplibre.org/martin/) for complete documentation. @@ -16,7 +16,7 @@ See [Martin book](https://maplibre.org/martin/) for complete documentation. ## Requirements -When using Martin with PostgreSQL, you must install PostGIS with at least v3.0+, and v3.1+ is recommended. +If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended. ## Installation @@ -39,18 +39,7 @@ brew tap maplibre/martin https://github.com/maplibre/martin.git brew install maplibre/martin/martin ``` -You can also use [official Docker image](https://ghcr.io/maplibre/martin) - -```shell -export PGPASSWORD=postgres # secret! -docker run \ - -p 3000:3000 \ - -e PGPASSWORD \ - -e DATABASE_URL=postgresql://user@host:port/db \ - ghcr.io/maplibre/martin -``` - -Use docker `-v` param to share configuration file or its directory with the container: +You can also use [official Docker image](https://ghcr.io/maplibre/martin), and share configuration file from the host with the container via the `-v` param. Config file is optional - you can let Martin auto-discover all sources e.g. by passing `DATABASE_URL` only. ```shell export PGPASSWORD=postgres # secret! @@ -63,27 +52,33 @@ docker run -p 3000:3000 \ ## Usage -### PostGIS sources +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 requires at least one PostgreSQL [connection string](https://maplibre.org/martin/PostgreSQL-Connection-String.html) or a [tile source file](https://maplibre.org/martin/MBTile-and-PMTile-Sources.html) as a command-line argument. A PG connection string can also be passed via the `DATABASE_URL` environment variable. +Martin can auto-discover tables and functions using a [connection string](https://maplibre.org/martin/PostgreSQL-Connection-String.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 -martin postgresql://user:password@host:port/database -``` +# publish all tables and functions from a single database +export DATABASE_URL=postgresql://user:password@host:port/database +martin -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. +# 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 -### MBTiles and PMTiles 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. For example: +# publish all discovered tables/funcs from two DBs +# and generate config file with all detected sources +martin postgres://... postgres://... --save-config config.yaml -```shell -martin /path/to/mbtiles/file.mbtiles -martin /path/to/directory +# use configuration file instead of auto-discovery +martin --config config.yaml ``` ## API -When started, Martin will go through all spatial tables and functions with an appropriate signature in the database. These tables and functions will be available as the HTTP endpoints, which you can use to query Mapbox vector tiles. +Martin data is available via the HTTP `GET` endpoints: | URL | Description | |----------------------------------------|-----------------------------------------------------------------------------------------------------------| diff --git a/docs/src/API.md b/docs/src/API.md index 65579ead..d4991966 100644 --- a/docs/src/API.md +++ b/docs/src/API.md @@ -1,13 +1,13 @@ # API -When started, Martin will go through all spatial tables and functions with an appropriate signature in the database. These tables and functions will be available as the HTTP endpoints, which you can use to query Mapbox vector tiles. +Martin data is available via the HTTP `GET` endpoints: -| Method | URL | Description | -|--------|----------------------------------------|---------------------------------------------------------| -| `GET` | `/` | Status text, that will eventually show web UI | -| `GET` | `/catalog` | [List of all sources](#source-list) | -| `GET` | `/{sourceID}` | [Source TileJSON](#table-source-tilejson) | -| `GET` | `/{sourceID}/{z}/{x}/{y}` | [Source Tiles](#table-source-tiles) | -| `GET` | `/{sourceID1},...,{nameN}` | [Composite Source TileJSON](#composite-source-tilejson) | -| `GET` | `/{sourceID1},...,{nameN}/{z}/{x}/{y}` | [Composite Source Tiles](#composite-source-tiles) | -| `GET` | `/health` | Martin server health check: returns 200 `OK` | +| URL | Description | +|----------------------------------------|-----------------------------------------------------------------------------------------------------------| +| `/` | Status text, that will eventually show web UI | +| `/catalog` | [List of all sources](https://maplibre.org/martin/source-list.html) | +| `/{sourceID}` | [Source TileJSON](https://maplibre.org/martin/table-sources.html#table-source-tilejson) | +| `/{sourceID}/{z}/{x}/{y}` | [Source Tiles](https://maplibre.org/martin/table-sources.html#table-source-tiles) | +| `/{sourceID1},...,{nameN}` | [Composite Source TileJSON](https://maplibre.org/martin/composite-sources.html#composite-source-tilejson) | +| `/{sourceID1},...,{nameN}/{z}/{x}/{y}` | [Composite Source Tiles](https://maplibre.org/martin/composite-sources.html#composite-source-tiles) | +| `/health` | Martin server health check: returns 200 `OK` |