Windshaft map tiler

A Node.js map tile server for PostGIS with CartoCSS styling.

• Pluggable routing to provide customizable tile API URL endpoints
• Before and after filters to allow custom access control and caching strategies
• Can render arbitrary SQL queries
• Generates image and UTFGrid interactivity tiles
• Accepts, stores, serves, and applies map styles written in CartoCSS
• Supports re-projections
• Allows setting of CORS headers to allow access to tile data from client side

Being a dynamic map renderer, windshaft commits some map server 'sins' in its raw form. The idea is that you the developer will want to graft your own auth/metrics/caching/scaling on top of decent core components. Same old story: high cohesion, low coupling makes us happy. See Windshaft-cartodb.

Windshaft is a library used by cartodb.com, an Open Source Geospatial Database on the Cloud.

Some examples

More examples built on top of Windshaft can be found in CartoDB's gallery.

Dependencies

• Node >=0.8
• npm >=1.2.1
• Mapnik 2.0.1, 2.0.2, 2.1.0, 2.2.0, 2.3.0. See Installing Mapnik.
• PostgreSQL >8.3.x, PostGIS >1.5.x
• Redis >2.2.x
• libcairo2-dev, libpango1.0-dev, libjpeg8-dev and libgif-dev for server side canvas support

Install

npm install

Usage

var Windshaft = require('windshaft');

// Configure pluggable URLs
// =========================
// The config object must define grainstore config (generally just
// postgres connection details), redis config, a base url and a function
// that adds 'dbname' and 'table' variables onto the Express.js req.params
// object.  In this example, the base URL is such that dbname and table will
// automatically be added to the req.params object by express.js. req2params
// can be extended to allow full control over the specifying of database
// parameters and also allows for the req.params object to be extended with
// other variables, such as:
//
// * sql - custom sql query to narrow results shown in map)
// * geom_type - specify the geom type (point|polygon) to get more
//               appropriate default styles
// * cache_buster - forces the creation of a new render object, nullifying
//                  existing metatile caches
// * interactivity - specify the column to use in the UTFGrid
//                   interactivity layer (defaults to null)
// * style - specify map style in the Carto map language on a per tile basis
//
// * dbuser - username for database connection
// * dbpassword - password for database connection
// * dbhost - database host
// * dbport - database port
// * dbname - database name
//
// the base url is also used for persisiting and retrieving map styles via:
//
// GET  base_url + '/style' (returns a map style)
// POST base_url + '/style' (allows specifying of a style in Carto markup
//                           in the 'style' form variable).
//
// beforeTileRender and afterTileRender could be defined if you want yo
// implement your own tile cache policy. See an example below

var config = {
        base_url: '/database/:dbname/table/:table',
        base_url_mapconfig: '/database/:dbname/layergroup',
        req2params: function(req, callback){
          callback(null,req)
        },
        grainstore: {
          datasource: {
            user:'postgres', host: '127.0.0.1',
            port: 5432
          }
        }, //see grainstore npm for other options
        renderCache: {
          ttl: 60000, // seconds
        },
        mapnik: {
          metatile: 4,
          bufferSize:64
        },
        redis: {host: '127.0.0.1', port: 6379},
        // this two filters are optional
        beforeTileRender: function(req, res, callback) {
            callback(null);
        },
        afterTileRender: function(req, res, tile, headers, callback) {
            callback(null, tile, headers);
        }
    };

// Initialize tile server on port 4000
var ws = new Windshaft.Server(config);
ws.listen(4000);
console.log("map tiles are now being served out of: http://localhost:4000"
            + config.base_url + '/:z/:x/:y.*');

// Specify .png, .png8 or .grid.json tiles.

See examples directory for running server and maptile viewer

Installing Mapnik

Latest node-mapnik versions comes compiled for some platforms and architectures, in case you need it you can always compile, package and install it manually. The recommended option is to use mapnik-packaging. You can also use other alternatives:

• Source: https://github.com/mapnik/mapnik
• OSX: https://github.com/mapnik/mapnik/wiki/MacInstallation_Homebrew
• Linux: https://github.com/mapnik/mapnik/wiki/LinuxInstallation

Tests

Windshaft has a unit and acceptance test suite. To execute them, run npm test.

You'll need to be sure your PGUSER (or your libpq default) is set to a "superuser" PostgreSQL account, for example:

PGUSER=postgres npm test

Troubleshooting

Uncaught Error: Command failed running tests

You need ImageMagick to run some tests. In Mac OS X there are some issues running with latest versions of ImageMagick. If you use Homebrew you can try with a modified Formula to install ImageMagick version 6.7.7.

Fonts: Invalid value for text-face-name

You need to install fonts at system level to be able to use them. If you face an issue like Invalid value for text-face-name, the type font is expected. DejaVu Sans Book (of type string) was given. probably you don't have the required fonts, try to install DejaVu fonts or any other font needed.

-- Thanks to the Mapnik and Mapbox team for making such flexible tools