docs: manual install guide for the map toolchain#461
Conversation
Add docs/map-tools-installation.md covering how to install GDAL, tippecanoe, and pmtiles by hand, for users running the standalone binary instead of the full Docker image. Per-platform instructions (Debian/Ubuntu, Fedora/RHEL, Alpine, macOS, Windows, conda), a per-tool reference, and troubleshooting. Documents the pmtiles go-install binary-name gotcha and the separate GDAL Python-tools package needed for gdal_calc.py / gdal_fillnodata.py. Tool status is surfaced via the maptool render preflight and the admin Map Manager page, so the guide points there rather than a non-existent subcommand. Link the guide from the README Docker section.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive guide for manually installing the map toolchain (GDAL, tippecanoe, and pmtiles) for standalone binary users, along with a reference in the README. The review feedback highlights a few necessary corrections: updating a non-existent Alpine version reference, adding instructions for ARM64 architecture downloads, and clarifying that tippecanoe is unavailable on Windows via conda-forge, meaning Windows users must use WSL2.
| |---|---| | ||
| | tippecanoe | `2.79.0` | | ||
| | go-pmtiles | `1.30.0` | | ||
| | GDAL | whatever Alpine 3.23 ships (GDAL 3.x) | |
There was a problem hiding this comment.
Alpine 3.23 is not a released version yet (as of early 2025, the latest stable is 3.21). Please check if this is a typo for 3.20, 3.21, or another version used in your Dockerfile.
| # 3. pmtiles — download the release binary (already named `pmtiles`) | ||
| # Replace the URL with the latest from https://github.com/protomaps/go-pmtiles/releases | ||
| curl -L -o pmtiles.tar.gz \ | ||
| https://github.com/protomaps/go-pmtiles/releases/download/v1.30.0/go-pmtiles_1.30.0_Linux_x86_64.tar.gz |
There was a problem hiding this comment.
Since OCAP2 supports both amd64 and arm64 architectures, it would be helpful to mention that ARM64 users should download the arm64 release of go-pmtiles instead of the hardcoded x86_64 one.
| # 3. pmtiles — download the release binary (already named `pmtiles`) | |
| # Replace the URL with the latest from https://github.com/protomaps/go-pmtiles/releases | |
| curl -L -o pmtiles.tar.gz \ | |
| https://github.com/protomaps/go-pmtiles/releases/download/v1.30.0/go-pmtiles_1.30.0_Linux_x86_64.tar.gz | |
| # 3. pmtiles — download the release binary (already named pmtiles) | |
| # Replace the URL with the latest from https://github.com/protomaps/go-pmtiles/releases | |
| # (For ARM64, use go-pmtiles_1.30.0_Linux_arm64.tar.gz instead) | |
| curl -L -o pmtiles.tar.gz \ | |
| https://github.com/protomaps/go-pmtiles/releases/download/v1.30.0/go-pmtiles_1.30.0_Linux_x86_64.tar.gz |
| 2. **tippecanoe** — there is no official native Windows build. Use one of: | ||
| - **WSL2** (recommended): run OCAP and follow the Debian/Ubuntu steps inside WSL. | ||
| - **conda** (cross-platform package below). |
There was a problem hiding this comment.
Because tippecanoe relies heavily on POSIX system calls (such as fork), it cannot be compiled natively on Windows and is not available for Windows on conda-forge. Therefore, Windows users must run OCAP and the toolchain inside WSL2.
| 2. **tippecanoe** — there is no official native Windows build. Use one of: | |
| - **WSL2** (recommended): run OCAP and follow the Debian/Ubuntu steps inside WSL. | |
| - **conda** (cross-platform package below). | |
| 2. **tippecanoe** — there is no official native Windows build, and it is not available for Windows on conda-forge. You must use **WSL2** to run OCAP and the toolchain inside a Linux environment (follow the Debian/Ubuntu steps). |
| conda-forge is GDAL's officially recommended cross-platform distribution and also | ||
| carries tippecanoe and pmtiles. This works identically on Linux, macOS, and Windows | ||
| and avoids compiling anything: |
There was a problem hiding this comment.
Since tippecanoe is not available for Windows on conda-forge, the conda installation command will fail on Windows. It is best to clarify that this works on Linux and macOS.
| conda-forge is GDAL's officially recommended cross-platform distribution and also | |
| carries tippecanoe and pmtiles. This works identically on Linux, macOS, and Windows | |
| and avoids compiling anything: | |
| conda-forge is GDAL's officially recommended cross-platform distribution and also | |
| carries tippecanoe and pmtiles. This works on Linux and macOS (note that tippecanoe | |
| is not available for Windows via conda) and avoids compiling anything: |
|
standalone "check tools" subcommand would be cool, so I don't have to go to the UI to see, if I can see the render maps icon. I would consider removing maxOS instructions - just makes it more cluttered. There is probably 0 people running ocap on macOS. |
2 participants
What
Adds
docs/map-tools-installation.md— a guide for installing the map toolchain (GDAL, tippecanoe, pmtiles) by hand.We ship two Docker images so people don't have to install these tools: the slim
latest/slimimage and thefullimage with the toolchain bundled (the toolchain is heavy, which is why it's split out). But since we also publish the standalone binary, some users want to install the tools themselves on their own host. This doc is for them.Contents
tippecanoe 2.79.0,go-pmtiles 1.30.0, GDAL 3.x).pmtiles— release binaries/Homebrew name itpmtiles, butgo installnames itgo-pmtiles; the pipeline only findspmtiles.tippecanoe— built from source (C++17), produces bothtippecanoeandtile-join.GDAL— thegdal_calc.py/gdal_fillnodata.pyPython scripts live in a separate package on most distros (python3-gdal/gdal-python-tools/py3-gdal).maptool renderpreflight and the admin Map Manager page (GET /api/v1/maptool/tools), plus troubleshooting.Linked from the README's Docker section.
Notes
Installation details were checked against each tool's current upstream docs/releases (release asset names, package names, and compiler requirements all verified). The tool list is derived from
internal/maptool/tools.go; verification guidance matches the actual CLI/handler behavior (there is no standalone "check tools" subcommand).