{"id":13426319,"url":"https://github.com/mojodna/tessera","last_synced_at":"2025-05-15T17:08:50.706Z","repository":{"id":11700710,"uuid":"14215357","full_name":"mojodna/tessera","owner":"mojodna","description":"A tilelive-based tile server.","archived":false,"fork":false,"pushed_at":"2024-07-21T16:47:05.000Z","size":398,"stargazers_count":324,"open_issues_count":28,"forks_count":79,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-05-15T17:08:42.528Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mojodna.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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,"zenodo":null}},"created_at":"2013-11-07T20:43:57.000Z","updated_at":"2024-10-25T21:54:35.000Z","dependencies_parsed_at":"2024-06-19T05:29:57.195Z","dependency_job_id":"87989fa4-bd8a-424b-a498-b95f7a710433","html_url":"https://github.com/mojodna/tessera","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojodna%2Ftessera","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojodna%2Ftessera/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojodna%2Ftessera/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mojodna%2Ftessera/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mojodna","download_url":"https://codeload.github.com/mojodna/tessera/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384989,"owners_count":22062422,"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":[],"created_at":"2024-07-31T00:01:31.758Z","updated_at":"2025-05-15T17:08:45.689Z","avatar_url":"https://github.com/mojodna.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Servers"],"sub_categories":[],"readme":"# tessera\n\ntessera is a [tilelive](https://github.com/mapbox/tilelive.js)-based tile\nserver.\n\nUsing the power of the tilelive ecosystem, it is capable of serving and\nrendering tiles from many sources.\n\n## Installation\n\n```bash\nnpm install -g tessera\nnpm install -g \u003ctilelive modules...\u003e\n```\n\n## How to Use\n\ntessera does not install tilelive providers itself; it is up to you to\n(globally) install any modules that you wish to use (along with dependencies\npresent in your configuration; e.g. a TM2 style that loads data tiles from an\nHTTP source).\n\nModules listed in\n[tilelive-modules](https://github.com/mojodna/tilelive-modules) will be\nauto-detected and loaded if they have been installed. For other modules, you\nwill need to `--require` them explicitly.\n\nTo serve up an [MBTiles](https://www.mapbox.com/developers/mbtiles/) archive\nusing [node-mbtiles](https://github.com/mapbox/node-mbtiles):\n\n```bash\nnpm install -g @mapbox/mbtiles\ntessera mbtiles://./whatever.mbtiles\n```\n\n_Note_: If you want to be able to preview vector tiles (MVT/PBF), you need these 2 modules:\n\n```bash\nnpm install -g tilelive-vector tilelive-xray\n```\n\n_Note_: If you want to render static maps from an endpoint, you'll need to use\n`~0.13.1`, as static map functionality was removed in `v0.14.0` to simplify\ndependencies (see [#86](https://github.com/mojodna/tessera/issues/86) for more\ncontext).\n\nTo serve up a [TileMill](https://www.mapbox.com/tilemill/) (or\n[Carto](https://github.com/mapbox/carto)) project using\n[tilelive-carto](https://github.com/mojodna/tilelive-carto):\n\n```bash\ntessera carto+file://./project.mml\n```\n\nTo serve up a [TM2](https://github.com/mapbox/tm2) style using\n[tilelive-tmstyle](https://github.com/mojodna/tilelive-tmstyle):\n\n```bash\ntessera tmstyle://./\n```\n\n**Note**: non-`mapbox:` sources may need to have their protocols changed;\ntessera requires that styles using HTTP-accessible data have `tilejson+http:`\nas their protocol where TM2 expects `http:`.  See\n[mojodna/tilelive-http#2](https://github.com/mojodna/tilelive-http/issues/2)\nfor more information.\n\nTo serve up a [TM2](https://github.com/mapbox/tm2) data source (it will use\n`data.yml` as the source of truth) using\n[tilelive-tmsource](https://github.com/mojodna/tilelive-tmsource):\n\n```bash\ntessera tmsource://./\n```\n\nTo serve up a bare [Mapnik](https://github.com/mapnik/mapnik) stylesheet using\n[tilelive-mapnik](https://github.com/mapbox/tilelive-mapnik):\n\n```bash\ntessera mapnik://./stylesheet.xml\n```\n\nTo serve up files from a filesystem using\n[tilelive-file](https://github.com/mapbox/tilelive-file):\n\n```bash\ntessera file://./tiles\n```\n\nTo proxy HTTP-accessible tiles using\n[tilelive-http](https://github.com/mojodna/tilelive-http):\n\n```bash\ntessera http://tile.stamen.com/toner/{z}/{x}/{y}.png\n```\n\nTo proxy Mapbox-hosted tiles using\n[tilelive-mapbox](https://github.com/mojodna/tilelive-mapbox):\n\n```bash\ntessera mapbox:///mapbox.mapbox-streets-v4\n```\n\nTo proxy tiles with available\n[TileJSON](https://www.mapbox.com/developers/tilejson/) using\n[node-tilejson](https://github.com/mapbox/node-tilejson):\n\n```bash\ntessera tilejson+http://a.tiles.mapbox.com/v3/mapbox.mapbox-streets-v4.json\n```\n\nA [TileJSON](https://github.com/mapbox/tilejson-spec/tree/master/2.2.0) endpoint is available at /[PATH]/index.json (for instance, localhost:8080/index.json), containing metadata about the tiles being served.\n\n## Configuration\n\nTessera has command-line options:\n\n```bash\nUsage: node tessera.js [uri] [options]\n\nuri     tilelive URI to serve\n\nOptions:\n   -C SIZE, --cache-size SIZE          Set the cache size (in MB)  [10]\n   -c CONFIG, --config CONFIG          Provide a configuration file or directory\n   -p PORT, --port PORT                Set the HTTP Port  [8080]\n   -b HOST, --bind HOST                Set interface to listen on [0.0.0.0]\n   -m, --multiprocess                  Start multiple processes  [false]\n   -P, --processes                     Number of processes to start  [8]\n   -r MODULE, --require MODULE         Require a specific tilelive module\n   -S SIZE, --source-cache-size SIZE   Set the source cache size (in # of sources)  [10]\n   -s SOCKET, --socket SOCKET          Listen on unix socket\n   -v, --version                       Show version info\n\nA tilelive URI or configuration file is required.\n```\n\nCommonly used options can be set using the `TESSERA_OPTS` environment variable.\n\nThis is what a configuration file looks like:\n\n```javascript\n{\n  \"/\": {\n    \"source\": \"mbtiles:///Users/seth/archive.mbtiles\",\n    \"cors\": false,\n    \"timing\": false\n  },\n  \"/a\": {\n    \"source\": \"mbtiles:///Users/seth/archive.mbtiles\",\n    \"headers\": {\n      \"Cache-Control\": \"public,max-age={{#tileJSON}}86400{{/tileJSON}}{{#tile}}3600{{/tile}}\",\n      \"Surrogate-Control\": \"max-age=86400\",\n      \"Surrogate-Keys\": \"{{#tile}}z{{zoom}} x{{x}} y{{y}}{{/tile}}\"\n    }\n  },\n  \"/b\": \"mbtiles:///Users/seth/archive.mbtiles\"\n}\n```\n\nHeader values are treated as\n[Mustache](http://mustache.github.io/mustache.5.html) (technically\n[Handlebars](http://handlebarsjs.com/)) templates, which allow them to vary by\nrequest. The following variables are available to header templates:\n\n* `tile.retina` - for retina (`@2x`) requests\n* `tile.zoom` - zoom (for tile requests)\n* `tile.x` - row (for tile requests)\n* `tile.y` - column (for tile requests)\n* `tile.format` - requested format\n* `tileJSON` - for TileJSON requests\n* `200` - HTTP 200\n* `404` - HTTP 404\n* `invalidFormat` - the requested format did not match what the tilelive source\n  provides\n* `invalidZoom` - the requested zoom is outside the available range\n* `invalidCoordinates` - the requested coordinates are outside the available bounds\n\nCORS and `X-Response-Time` can be disabled per-style:\n\n```javascript\n{\n  \"cors\": false,\n  \"timing\": false\n}\n```\n\n(Note that enabling for `/` will propagate to all subdirectories, as they act\nas middleware.)\n\nCustom tile paths may be set per-style:\n\n```javascript\n{\n  \"tilePath\": \"/{z}/{x}/{y}-debug.{format}\"\n}\n```\n\nThe default tile path is:\n\n```javascript\n{\n  \"tilePath\": \"/{z}/{x}/{y}.{format}\"\n}\n```\n\n(_Note_: the final `.` will be expanded to transparently support retina\nrequests (effectively `/{z}/{x}/{y}@2x.{format}`).)\n\nIf `--config` is set to a directory, all JSON files in it will be concatenated\ntogether to form a single configuration. In the case of repeated options or\npaths, the last one will win (where files are loaded in alphabetical order).\n\nFor sources that render rasters from vector tiles at and have a max zoom level\nthat is higher than the max zoom level of the vector tiles it can be helpful to\nhave additional variables available for headers that represent the vector tile\nthat a raster was rendered from. This can be enabled with an additional source\noption in the configuration file:\n\n```javascript\n{\n  \"sourceMaxZoom\": 14\n}\n```\n\nThis will make three additional values available for header templates:\n* `tile.sourceZoom`\n* `tile.sourceX`\n* `tile.sourceY`\n\nFor example: if `sourceMaxZoom` is set to 14, a request for tile 16/100/100\nwill set the following variables:\n\n* `tile.sourceZoom = 14`\n* `tile.sourceX = 25`\n* `tile.sourceY = 25`\n\n## Multiprocess mode\n\nBy default, tessera runs in a single process (modules, e.g. Mapnik, may use\nmultiple threads). For sources that are CPU intensive  to render, or when\nrunning on servers with large numbers of CPU cores there can be significant\nperformance improvements from running in multiprocess mode. When multiprocess\nmode is enabled with the `--multiprocess` option multiple processes will be\nstarted, with each process running a single thread, enabling many requests to be\nserved at once. The number of processes to be started defaults to the number of\nCPU cores on the host, but can be configured with the `--processes` option.\n\n## Environment Variables\n\n* `PORT` - Port to bind to. Defaults to `8080`.\n* `HOST` - Interface to listen on. Defaults to `0.0.0.0` (all).\n* `CACHE_SIZE` - Cache size (in MB) for\n  [tilelive-cache](https://github.com/mojodna/tilelive-cache). Defaults to\n  10MB.\n* `SOCKET` - Unix socket to bind to. Optional.\n* `SOURCE_CACHE_SIZE` - Number of sources to cache (for\n  [tilelive-cache](https://github.com/mojodna/tilelive-cache)). Defaults to 6.\n  *NOTE*: implicit retina versions count as an extra source.\n* `TESSERA_OPTS` - Additional command-line arguments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmojodna%2Ftessera","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmojodna%2Ftessera","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmojodna%2Ftessera/lists"}