Skip to content

Commit 69f7383

Browse files
petrslouppetrsloup
committed
New README.md
1 parent 49b100e commit 69f7383

File tree

1 file changed

+31
-189
lines changed

1 file changed

+31
-189
lines changed

‎README.md

+31-189
Original file line numberDiff line numberDiff line change
@@ -1,210 +1,52 @@
1-
# tessera
1+
# tileserver-mapnik
22

3-
tessera is a [tilelive](https://github.com/mapbox/tilelive.js)-based tile
4-
server.
3+
Mapnik-based tile server generating raster tiles from tilelive-js sources (MapBox Studio project + custom vector tiles for example).
4+
It supports also static maps API.
55

6-
Using the power of the tilelive ecosystem, it is capable of serving and
7-
rendering tiles from many sources.
6+
## How to use
87

9-
## Installation
8+
### Docker
109

11-
```bash
12-
npm install -g tessera
13-
npm install -g <tilelive modules...>
14-
```
15-
16-
## How to Use
17-
18-
tessera does not install tilelive providers itself; it is up to you to
19-
(globally) install any modules that you wish to use (along with dependencies
20-
present in your configuration; e.g. a TM2 style that loads data tiles from an
21-
HTTP source).
22-
23-
Modules listed in
24-
[tilelive-modules](https://github.com/mojodna/tilelive-modules) will be
25-
auto-detected and loaded if they have been installed. For other modules, you
26-
will need to `--require` them explicitly.
27-
28-
To serve up an [MBTiles](https://www.mapbox.com/developers/mbtiles/) archive
29-
using [node-mbtiles](https://github.com/mapbox/node-mbtiles):
30-
31-
```bash
32-
npm install -g mbtiles
33-
tessera mbtiles://./whatever.mbtiles
34-
```
35-
36-
To serve up a [TileMill](https://www.mapbox.com/tilemill/) (or
37-
[Carto](https://github.com/mapbox/carto)) project using
38-
[tilelive-carto](https://github.com/mojodna/tilelive-carto):
39-
40-
```bash
41-
tessera carto+file://./project.mml
42-
```
43-
44-
To serve up a [TM2](https://github.com/mapbox/tm2) style using
45-
[tilelive-tmstyle](https://github.com/mojodna/tilelive-tmstyle):
46-
47-
```bash
48-
tessera tmstyle://./
49-
```
50-
51-
**Note**: non-`mapbox:` sources may need to have their protocols changed;
52-
tessera requires that styles using HTTP-accessible data have `tilejson+http:`
53-
as their protocol where TM2 expects `http:`. See
54-
[mojodna/tilelive-http#2](https://github.com/mojodna/tilelive-http/issues/2)
55-
for more information.
56-
57-
To serve up a [TM2](https://github.com/mapbox/tm2) data source (it will use
58-
`data.yml` as the source of truth) using
59-
[tilelive-tmsource](https://github.com/mojodna/tilelive-tmsource):
60-
61-
```bash
62-
tessera tmsource://./
63-
```
64-
65-
To serve up a bare [Mapnik](https://github.com/mapnik/mapnik) stylesheet using
66-
[tilelive-mapnik](https://github.com/mapbox/tilelive-mapnik):
67-
68-
```bash
69-
tessera mapnik://./stylesheet.xml
70-
```
71-
72-
To serve up files from a filesystem using
73-
[tilelive-file](https://github.com/mapbox/tilelive-file):
74-
75-
```bash
76-
tessera file://./tiles
77-
```
78-
79-
To proxy HTTP-accessible tiles using
80-
[tilelive-http](https://github.com/mojodna/tilelive-http):
81-
82-
```bash
83-
tessera http://tile.stamen.com/toner/{z}/{x}/{y}.png
84-
```
85-
86-
To proxy Mapbox-hosted tiles using
87-
[tilelive-mapbox](https://github.com/mojodna/tilelive-mapbox):
88-
89-
```bash
90-
tessera mapbox:///mapbox.mapbox-streets-v4
91-
```
10+
The easiest way to run tileserver-mapnik is using the precompiled docker container (https://hub.docker.com/r/klokantech/tileserver-mapnik/).
9211

93-
To proxy tiles with available
94-
[TileJSON](https://www.mapbox.com/developers/tilejson/) using
95-
[node-tilejson](https://github.com/mapbox/node-tilejson):
12+
Detailed instructions how to use the tileserver-mapnik with docker: http://osm2vectortiles.org/docs/serve-raster-tiles-docker/
9613

97-
```bash
98-
tessera tilejson+http://a.tiles.mapbox.com/v3/mapbox.mapbox-streets-v4.json
99-
```
100-
101-
A TileJSON endpoint is available at
102-
[localhost:8080/index.json](http://localhost:8080/index.json) with various bits
103-
of metadata about the tiles being served.
104-
105-
## Configuration
106-
107-
Tessera has command-line options:
14+
### Without docker
10815

109-
```bash
110-
Usage: node tessera.js [uri] [options]
16+
Follow the commands in `Dockerfile` to install the necessary packages, download common fonts and prepare the environment.
11117

112-
uri tilelive URI to serve
18+
Usage: `node bin/tessera.js [options]`
11319

11420
Options:
115-
-C SIZE, --cache-size SIZE Set the cache size (in MB) [10]
116-
-c CONFIG, --config CONFIG Provide a configuration file or directory
117-
-p PORT, --port PORT Set the HTTP Port [8080]
118-
-r MODULE, --require MODULE Require a specific tilelive module
119-
-S SIZE, --source-cache-size SIZE Set the source cache size (in # of sources) [10]
120-
-v, --version Show version info
21+
- `-c CONFIG` - Configuration file
22+
- `-p PORT` - HTTP port [8080]
23+
- `-C SIZE` - Cache size in MB [10]
24+
- `-S SIZE` - Source cache size (in # of sources) [10]
12125

122-
A tilelive URI or configuration file is required.
123-
```
124-
125-
Commonly used options can be set using the `TESSERA_OPTS` environment variable.
126-
127-
This is what a configuration file looks like:
26+
#### Example configuration file
12827

12928
```javascript
13029
{
131-
"/": {
132-
"source": "mbtiles:///Users/seth/archive.mbtiles",
133-
"cors": false,
134-
"timing": false
30+
"/style1": {
31+
"source": "tmstyle://./style1.tm2"
13532
},
136-
"/a": {
137-
"source": "mbtiles:///Users/seth/archive.mbtiles",
138-
"headers": {
139-
"Cache-Control": "public,max-age={{#tileJSON}}86400{{/tileJSON}}{{#tile}}3600{{/tile}}",
140-
"Surrogate-Control": "max-age=86400",
141-
"Surrogate-Keys": "{{#tile}}z{{zoom}} x{{x}} y{{y}}{{/tile}}"
142-
}
33+
"/style2": {
34+
"source": "tmstyle:///home/user/style2.tm2"
14335
},
144-
"/b": "mbtiles:///Users/seth/archive.mbtiles"
145-
}
146-
```
147-
148-
Header values are treated as
149-
[Mustache](http://mustache.github.io/mustache.5.html) (technically
150-
[Handlebars](http://handlebarsjs.com/)) templates, which allow them to vary by
151-
request. The following variables are available to header templates:
152-
153-
* `tile.retina` - for retina (`@2x`) requests
154-
* `tile.zoom` - zoom (for tile requests)
155-
* `tile.x` - row (for tile requests)
156-
* `tile.y` - column (for tile requests)
157-
* `tile.format` - requested format
158-
* `tileJSON` - for TileJSON requests
159-
* `200` - HTTP 200
160-
* `404` - HTTP 404
161-
* `invalidFormat` - the requested format did not match what the tilelive source
162-
provides
163-
* `invalidZoom` - the requested zoom is outside the available range
164-
* `invalidCoordinates` - the requested coordinates are outside the available bounds
165-
166-
CORS and `X-Response-Time` can be disabled per-style:
167-
168-
```javascript
169-
{
170-
"cors": false,
171-
"timing": false
36+
"/vector": {
37+
"source": "mbtiles:///home/user/data.mbtiles"
38+
}
17239
}
17340
```
17441

175-
(Note that enabling for `/` will propagate to all subdirectories, as they act
176-
as middleware.)
177-
178-
Custom tile paths may be set per-style:
179-
180-
```javascript
181-
{
182-
"tilePath": "/{z}/{x}/{y}-debug.{format}"
183-
}
184-
```
185-
186-
The default tile path is:
187-
188-
```javascript
189-
{
190-
"tilePath": "/{z}/{x}/{y}.{format}"
191-
}
192-
```
193-
194-
(_Note_: the final `.` will be expanded to transparently support retina
195-
requests (effectively `/{z}/{x}/{y}@2x.{format}`).)
196-
197-
If `--config` is set to a directory, all JSON files in it will be concatenated
198-
together to form a single configuration. In the case of repeated options or
199-
paths, the last one will win (where files are loaded in alphabetical order).
42+
**Note**: For tm2 styles, you need to make sure the content of style's `project.yml` (its `source` property) points to a valid mbtiles file (e.g. `source: "mbtiles://./data.mbtiles"`).
20043

201-
## Environment Variables
44+
## Available URLs
20245

203-
* `PORT` - Port to bind to. Defaults to `8080`.
204-
* `CACHE_SIZE` - Cache size (in MB) for
205-
[tilelive-cache](https://github.com/mojodna/tilelive-cache). Defaults to
206-
10MB.
207-
* `SOURCE_CACHE_SIZE` - Number of sources to cache (for
208-
[tilelive-cache](https://github.com/mojodna/tilelive-cache)). Defaults to 6.
209-
*NOTE*: implicit retina versions count as an extra source.
210-
* `TESSERA_OPTS` - Additional command-line arguments.
46+
- If you visit the server on the configured port (default 8080) you should see your maps appearing in the browser.
47+
- The tiles itself are served at `/{basename}/{z}/{x}/{y}[@2x].{format}`
48+
- The optional `@2x` part can be used to render HiDPI (retina) tiles
49+
- Static images are rendered at:
50+
- `/{basename}/static/{lon},{lat},{zoom}/{width}x{height}[@2x].{format}` (center-based)
51+
- `/{basename}/static/{minx},{miny},{maxx},{maxy}/{zoom}[@2x].{format}` (area-based)
52+
- TileJSON at `/{basename}/index.json`

0 commit comments

Comments
 (0)