mirror of
https://github.com/maptiler/tileserver-gl.git
synced 2024-09-11 03:55:27 +03:00
Initial documentation (close #39)
This commit is contained in:
parent
97457a23f2
commit
25c87ccf23
1
.gitignore
vendored
1
.gitignore
vendored
@ -1,3 +1,4 @@
|
||||
docs/_build
|
||||
node_modules
|
||||
test_data
|
||||
data
|
||||
|
112
docs/config.rst
Normal file
112
docs/config.rst
Normal file
@ -0,0 +1,112 @@
|
||||
==================
|
||||
Configuration file
|
||||
==================
|
||||
|
||||
The configuration file defines the behavior of the application. It's a regular JSON file.
|
||||
|
||||
Example::
|
||||
|
||||
{
|
||||
"options": {
|
||||
"paths": {
|
||||
"root": "",
|
||||
"fonts": "glyphs",
|
||||
"sprites": "sprites",
|
||||
"styles": "styles",
|
||||
"mbtiles": ""
|
||||
},
|
||||
"domains": [
|
||||
"localhost:8080",
|
||||
"127.0.0.1:8080"
|
||||
],
|
||||
"formatQuality": {
|
||||
"png": 90,
|
||||
"jpeg": 80,
|
||||
"webp": 90
|
||||
}
|
||||
},
|
||||
"styles": {
|
||||
"basic": {
|
||||
"style": "basic.json",
|
||||
"tilejson": {
|
||||
"type": "overlay",
|
||||
"bounds": [8.44806, 47.32023, 8.62537, 47.43468]
|
||||
}
|
||||
},
|
||||
"hybrid": {
|
||||
"style": "satellite-hybrid.json",
|
||||
"serve_rendered": false,
|
||||
"tilejson": {
|
||||
"format": "webp"
|
||||
}
|
||||
}
|
||||
},
|
||||
"data": {
|
||||
"zurich-vector": {
|
||||
"mbtiles": "zurich.mbtiles"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
``options``
|
||||
===========
|
||||
|
||||
``paths``
|
||||
---------
|
||||
|
||||
Defines where to look for the different types of input data.
|
||||
|
||||
The value of ``root`` is used as prefix for all data types.
|
||||
|
||||
``domains``
|
||||
-----------
|
||||
|
||||
You can use this to optionally specify on what domains the rendered tiles are accessible. This can be used for basic load-balancing or to bypass browser's limit for the number of connections per domain.
|
||||
|
||||
``formatQuality``
|
||||
-----------------
|
||||
|
||||
Quality of the compression of individual image formats. [0-100]
|
||||
|
||||
``styles``
|
||||
==========
|
||||
|
||||
Each item in this object defines one style (map). It can have the following options:
|
||||
|
||||
* ``style`` -- name of the style json file [required]
|
||||
* ``serve_rendered`` -- whether to render the raster tiles for this style or not
|
||||
* ``serve_data`` -- whether to allow acces to the original tiles, sprites and required glyphs
|
||||
* ``tilejson`` -- properties to add to the TileJSON created for the raster data
|
||||
|
||||
* ``format`` and ``bounds`` can be especially useful
|
||||
|
||||
``data``
|
||||
========
|
||||
|
||||
Each item specifies one data source which should be made accessible by the server. It has the following options:
|
||||
|
||||
* ``mbtiles`` -- name of the mbtiles file [required]
|
||||
|
||||
The mbtiles file does not need to be specified here unless you explicitly want to serve the raw data.
|
||||
|
||||
Referencing local mbtiles from style
|
||||
====================================
|
||||
|
||||
You can link various data sources from the style JSON (for example even remote TileJSONs).
|
||||
|
||||
To specify that you want to use local mbtiles, use to following syntax: ``mbtiles://switzerland.mbtiles``.
|
||||
The TileServer-GL will try to find the file ``switzerland.mbtiles`` in ``root`` + ``mbtiles`` path.
|
||||
|
||||
For example::
|
||||
|
||||
"sources": {
|
||||
"source1": {
|
||||
"url": "mbtiles://switzerland.mbtiles",
|
||||
"type": "vector"
|
||||
}
|
||||
}
|
||||
|
||||
Alternatively, you can use ``mbtiles://{zurich-vector}`` to reference existing data object from the config.
|
||||
In this case, the server will look into the ``config.json`` to determine what mbtiles file to use.
|
||||
For the config above, this is equivalent to ``mbtiles://zurich.mbtiles``.
|
15
docs/deployment.rst
Normal file
15
docs/deployment.rst
Normal file
@ -0,0 +1,15 @@
|
||||
==========
|
||||
Deployment
|
||||
==========
|
||||
|
||||
Typically - you should use nginx/lighttpd/apache on the frontend - and the tileserver-gl server is hidden behind it in production deployment.
|
||||
|
||||
Caching
|
||||
=======
|
||||
|
||||
There is a plenty of options you can use to create proper caching infrastructure: Varnish, CloudFlare, ...
|
||||
|
||||
Securing
|
||||
========
|
||||
|
||||
Nginx can be used to add protection via https, password, referrer, IP address restriction, access keys, etc.
|
52
docs/endpoints.rst
Normal file
52
docs/endpoints.rst
Normal file
@ -0,0 +1,52 @@
|
||||
===================
|
||||
Available endpoints
|
||||
===================
|
||||
|
||||
If you visit the server on the configured port (default 8080) you can see your maps appearing in the browser.
|
||||
|
||||
Styles
|
||||
======
|
||||
* Styles are served at ``/styles/{id}.json`` (+ array at ``/styles.json``)
|
||||
|
||||
* Sprites at ``/styles/{id}/sprite[@2x].{format}``
|
||||
* Fonts at ``/fonts/{fontstack}/{start}-{end}.pbf``
|
||||
|
||||
Rendered tiles
|
||||
==============
|
||||
* Rendered tiles are served at ``/styles/{id}/rendered/{z}/{x}/{y}[@2x].{format}``
|
||||
|
||||
* The optional ``@2x`` (or ``@3x``) part can be used to render HiDPI (retina) tiles
|
||||
* Available formats: ``png``, ``jpg`` (``jpeg``), ``webp``
|
||||
* TileJSON at ``/styles/{id}/rendered.json``
|
||||
|
||||
Static images
|
||||
=============
|
||||
* Several endpoints:
|
||||
|
||||
* ``/styles/{id}/static/{lon},{lat},{zoom}[@{bearing}[,{pitch}]]/{width}x{height}[@2x].{format}`` (center-based)
|
||||
* ``/styles/{id}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}[@2x].{format}`` (area-based)
|
||||
* ``/styles/{id}/static/auto/{width}x{height}[@2x].{format}`` (autofit path -- see below)
|
||||
|
||||
* All the static image endpoints additionally support following query parameters:
|
||||
|
||||
* ``path`` - comma-separated ``lng,lat``, pipe-separated pairs
|
||||
|
||||
* e.g. ``5.9,45.8|5.9,47.8|10.5,47.8|10.5,45.8|5.9,45.8``
|
||||
|
||||
* ``latlng`` - indicates the ``path`` coordinates are in ``lat,lng`` order rather than the usual ``lng,lat``
|
||||
* ``fill`` - color to use as the fill (e.g. ``red``, ``rgba(255,255,255,0.5)``, ``#0000ff``)
|
||||
* ``stroke`` - color of the path stroke
|
||||
* ``width`` - width of the stroke
|
||||
* ``padding`` - "percetange" padding for fitted endpoints (area-based and path autofit)
|
||||
|
||||
* value of ``0.1`` means "add 10% size to each side to make sure the area of interest is nicely visible"
|
||||
|
||||
Source data
|
||||
===========
|
||||
* Source data are served at ``/data/{mbtiles}/{z}/{x}/{y}.{format}``
|
||||
|
||||
* TileJSON at ``/data/{mbtiles}.json``
|
||||
|
||||
TileJSON arrays
|
||||
===============
|
||||
Array of all TileJSONs is at ``/index.json`` (``/rendered.json``; ``/data.json``)
|
@ -11,6 +11,12 @@ Contents:
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
usage
|
||||
config
|
||||
deployment
|
||||
endpoints
|
||||
|
||||
|
||||
|
||||
Indices and tables
|
||||
|
24
docs/installation.rst
Normal file
24
docs/installation.rst
Normal file
@ -0,0 +1,24 @@
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
Docker
|
||||
======
|
||||
|
||||
When running docker image, no special installation is needed -- the docker will automatically download the image if not present.
|
||||
|
||||
Just run ``docker run -it -v $(pwd):/data -p 8080:80 klokantech/tileserver-gl``.
|
||||
|
||||
NPM
|
||||
===
|
||||
|
||||
Just run ``npm install -g tileserver-gl``.
|
||||
|
||||
|
||||
From source
|
||||
===========
|
||||
|
||||
Make sure you have Node v4 or higher (nvm install 4) and run::
|
||||
|
||||
npm install
|
||||
node .
|
28
docs/usage.rst
Normal file
28
docs/usage.rst
Normal file
@ -0,0 +1,28 @@
|
||||
=====
|
||||
Usage
|
||||
=====
|
||||
|
||||
Getting started
|
||||
======
|
||||
|
||||
::
|
||||
|
||||
Usage: tileserver-gl [mbtiles] [options]
|
||||
|
||||
mbtiles MBTiles file (uses demo configuration);
|
||||
ignored if the configuration file is also specified
|
||||
|
||||
Options:
|
||||
-c, --config Configuration file [config.json]
|
||||
-b, --bind Bind address
|
||||
-p, --port Port [8080]
|
||||
-V, --verbose More verbose output
|
||||
-v, --version Version info
|
||||
|
||||
|
||||
|
||||
Default styles and configuration
|
||||
======
|
||||
|
||||
- If no configuration file is specified, the default styles (compatible with osm2vectortiles) are used.
|
||||
- If no mbtiles file is specified (and is not found in the current working directory), an extract is downloaded directly from osm2vectortiles.
|
Loading…
Reference in New Issue
Block a user