{"id":18069680,"url":"https://github.com/pnorman/tilekiln","last_synced_at":"2025-06-14T21:04:05.225Z","repository":{"id":133271450,"uuid":"554376965","full_name":"pnorman/tilekiln","owner":"pnorman","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-12T01:48:05.000Z","size":224,"stargazers_count":59,"open_issues_count":27,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-12T02:50:34.187Z","etag":null,"topics":["openstreetmap","postgis","vector-tiles"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pnorman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-19T17:59:15.000Z","updated_at":"2025-06-12T01:47:40.000Z","dependencies_parsed_at":"2023-12-22T22:29:27.931Z","dependency_job_id":"2a4635dc-95b1-44d2-911a-6c8b5afb354b","html_url":"https://github.com/pnorman/tilekiln","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/pnorman/tilekiln","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnorman%2Ftilekiln","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnorman%2Ftilekiln/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnorman%2Ftilekiln/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnorman%2Ftilekiln/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pnorman","download_url":"https://codeload.github.com/pnorman/tilekiln/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnorman%2Ftilekiln/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259387262,"owners_count":22849739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openstreetmap","postgis","vector-tiles"],"created_at":"2024-10-31T08:10:59.650Z","updated_at":"2025-06-14T21:04:05.205Z","avatar_url":"https://github.com/pnorman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tilekiln\n\n## Background\n\nTilekiln is a set of command-line utilities to generate and serve Mapbox Vector Tiles (MVTs).\n\nGeneration relies on the standard method of a PostgreSQL + PostGIS server as a data source, and ST_AsMVT to serialize the MVTs.\n\nThe target use-case is vector tiles for a worldwide complex basemap under high load which requires minutely updates. If only daily updates are required options like [tilemaker](https://tilemaker.org/) or [planetiler](https://github.com/onthegomap/planetiler) may be simpler to host.\n\n## Requirements\n\nTilekiln requires a PostGIS database with data loaded to generate vector tiles.\n\n[OpenStreetMap Carto's](https://github.com/gravitystorm/openstreetmap-carto/blob/master/INSTALL.md#openstreetmap-data) directions are a good starting place for loading OpenStreetMap data into a PostGIS database, but any PostGIS data source in EPSG 3857 will work.\n\n- PostgreSQL 10+\n- PostGIS 3.1+\n- Python 3.10\n\n## Concepts\n\nTilekiln issues queries against a *source* database to generate Mapbox Vector Tile (MVT) layers, assembles the layers into a tile, then either serves the tile to the user or stores it in a *storage* database. It can also serve previously generated tiles from the *storage* database which completely removes the *source* database out of the critical path for serving tiles.\n\nUtility commands allow checking of configurations, storage management, and debugging as well as commands for monitoring metrics needed in production.\n\n## Usage\nTilekiln commands can be broken into two sets, commands which involve serving tiles, and CLI commands. Command-line options can be found with `tilekiln --help`, which includes a listing and description of all options.\n\n### CLI commands\nCLI commands will perform a task then exit, returning to ther shell.\n\n#### `config`\nCommands to work with and check config files\n\n##### `config test`\nTests a config for validity.\n\nThe process will exit with exit code 0 if tilekiln can load the config.\n\nThis is intended for build and CI scripts used by configs.\n\n##### `config sql`\nPrint the SQL for a tile or layer.\n\nPrints the SQL that would be issued to generate a particular tile layer,\nor if no layer is given, the entire tile. This allows manual debugging of\na tile query.\n\n#### `generate`\nCommands for tile generation.\n\nAll tile generation commands run queries against the source database which\nhas the geospatial data.\n\n##### `generate tiles`\nGenerate specific tiles.\n\nA list of z/x/y tiles is read from stdin and those tiles are generated and\nsaved to storage. The entire list is read before deletion starts.\n\n##### `generate zoom`\nGenerate all tiles by zoom.\n\n##### `generate layers`\nGenerate specific layers for specific tiles.\n\n#### `storage`\nCommands working with tile storage.\n\nThese commands allow creation and manipulation of the tile storage database.\n\n##### `storage init`\nInitialize storage for a tileset.\n\nCreates the storage for a tile layer and stores its metadata in the database.\nIf the metadata tables have not yet been created they will also be setup.\n\n##### `storage destroy`\nDestroy storage for a tileset.\n\nRemoves the storage for a tile layer and deletes its associated metadata.\nThe metadata tables themselves are not removed.\n\n##### `storage inspect`\nPrint data about a stored tile\n\n##### `storage delete`\nMass-delete tiles from a tileset\n\nDeletes tiles from a tileset, by zoom, or delete all zooms.\n\n##### `storage tiledelete`\nDelete specific tiles.\n\nA list of z/x/y tiles is read from stdin and those tiles are deleted from\nstorage. The entire list is read before deletion starts.\n\n### Serving commands\nThese commands start a HTTP server to serve content.\n#### `serve`\nCommands for tile serving.\n\nAll tile serving commands serve tiles and a tilejson over HTTP.\n\n##### `dev`\nStarts a server to live-render tiles with no caching, intended for development. It presents a tilejson at `/\u003cid\u003e/tilejson.json`, and for convience `/tilejson.json` redirects to it.\n\n##### `live`\nLike `serve`, but fall back to live generation if a tile is missing from storage.\n\nIt presents a tilejson at `/\u003cid\u003e/tilejson.json`.\n\n##### `static`\nServes tiles from tile storage. This is highly scalable and the preferred mode for production.\n\nIt presents a tilejson at `/\u003cid\u003e/tilejson.json`. In the future it will allow serving multiple tilesets.\n\n#### `prometheus`\nStarts a prometheus exporter for metrics on tiles. By default it presents metrics at `http://127.0.0.1:10013/metrics`.\n\n## Quick-start\nThese instructions give you a setup based on osm2pgsql-themepark and their shortbread setup. They assume you have PostgreSQL with PostGIS and Python 3.10+ with venv set up, and a recent version of osm2pgsql.\n\n### Install and setup\n\n```sh\npython3 -m venv tilekiln\ntilekiln/bin/pip install tilekiln\ntilekiln/bin/tilekiln --help\n```\n\n### Configuration Setup\n\nTilekiln requires a configuration file that defines the contents of your vector tiles. Most configurations are designed to work with OpenStreetMap data loaded into PostgreSQL using osm2pgsql.\n\nFor a configuration, you can use the one provided by the [Street Spirit](https://github.com/pnorman/spirit) project. Follow its [installation guide](https://github.com/pnorman/spirit/blob/main/INSTALL.md) to get started.\n\n## History\nThe tilekiln configuration syntax is based on studies and experience with other vector tile and map generation configurations. In particular, it is heavily inspired by Tilezen's use of Jinja2 templates and TileJSON for necessary metadata.\n\n## License\n\n### Code\n\nCopyright © 2022-2024 Paul Norman \u003cosm@paulnorman.ca\u003e\n\nThe code is licensed terms of the GNU General Public License as\npublished by the Free Software Foundation, either version 3 of\nthe License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\n### Documentation\n\nThe text of the documentation and configuration format specification is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). However, the use of the specification in products and code is entirely free: there are no royalties, restrictions, or requirements.\n\n### Sample configuration\n\nThe sample configuration files are released under the CC0 Public\nDomain Dedication, version 1.0, as published by Creative Commons.\nTo the extent possible under law, the author(s) have dedicated all\ncopyright and related and neighboring rights to the Software to\nthe public domain worldwide. The Software is distributed WITHOUT\nANY WARRANTY.\n\nIf you did not receive a copy of the CC0 Public Domain Dedication\nalong with the Software, see\n\u003chttp://creativecommons.org/publicdomain/zero/1.0/\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnorman%2Ftilekiln","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpnorman%2Ftilekiln","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnorman%2Ftilekiln/lists"}