Adjust readme and martin book (#1253)

Fixes #1245 Large book and README refactoring, adding quick started section, list of available features to the README, and moving most of the content from README to the book. --------- Co-authored-by: Yuri Astrakhan <[email protected]>
maplibre · May 26, 2024 · a9cb0c9 · a9cb0c9
1 parent 81f4d4c
commit a9cb0c9
Show file tree

Hide file tree

Showing 32 changed files with 386 additions and 233 deletions.
diff --git 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)<br>[.tar.gz][rl-linux-x64-musl] (musl)<br>[.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
@@ -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
@@ -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
@@ -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
diff --git a/docs/src/images/qgis_add_vector_tile.png b/docs/src/images/qgis_add_vector_tile.png
diff --git a/docs/src/images/qgis_add_vector_tile_options.png b/docs/src/images/qgis_add_vector_tile_options.png
diff --git a/docs/src/images/qgis_shows_in_the_map.png b/docs/src/images/qgis_shows_in_the_map.png
diff --git 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)<br>[.tar.gz][rl-linux-x64-musl] (musl)<br>[.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
@@ -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
@@ -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"      \