Initial documentation (close #39)

.gitignore

@@ -1,3 +1,4 @@
+docs/_build
 node_modules
 test_data
 data

docs/config.rst

@@ -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``.

docs/deployment.rst

@@ -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.

docs/endpoints.rst

@@ -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``)

docs/index.rst

@@ -11,6 +11,12 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   installation
+   usage
+   config
+   deployment
+   endpoints
+
 
 
 Indices and tables

docs/installation.rst

@@ -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 .

docs/usage.rst

@@ -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.