Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

Windshaft-CartoDB Build Status

The CARTO Maps API tiler. It extends Windshaft and exposes a web service with extra functionality:




PostGIS setup

A template_postgis database is expected. One can be set up with

$ createdb --owner postgres --template template0 template_postgis
$ psql -d template_postgis -c 'CREATE EXTENSION postgis;'


To fetch and build all node-based dependencies, run:

$ npm install


You can inject the configuration through environment variables at run time. Check the file ./config/environments/config.js to see the ones you have available.

While the migration to the new environment based configuration, you can still use the old method of copying a config file. To enabled the one with environment variables you need to pass CARTO_WINDSHAFT_ENV_BASED_CONF=true. You can use the docker image to run it.

Old way:

$ node app.js <env>

Where <env> is the name of a configuration file under ./config/environments/.


You can easily run the tests against the dependencies from the dev-env. To do so, you need to build the test docker image:

$ docker-compose build

Then you can run the tests like:

$ docker-compose run windshaft-tests

It will mount your code inside a volume. In case you want to play and run npm test or something else you can do:

$ docker-compose run --entrypoint bash windshaft-tests

So you will have a bash shell inside the test container, with the code from your host.


$ npm run cover

Open ./coverage/lcov-report/index.html.

Docker support

We provide docker images just for testing and continuous integration purposes:

You can find instructions to install Docker, download, and update images here.

Useful npm scripts

Run test in a docker image with a specific Node.js version:

$ DOCKER_IMAGE=<docker-image-tag> NODE_VERSION=<nodejs-version> npm run test:docker


  • <docker-image-tag>: the tag of required docker image, e.g. carto/nodejs-xenial-pg1121:latest
  • <nodejs-version>: the Node.js version, e.g. 10.15.1

In case you need to debug:

$ DOCKER_IMAGE=<docker-image-tag> npm run docker:bash


You can find an overview, guides, full reference, and support in CARTO's developer center. The docs directory contains different documentation resources, from a higher level to more detailed ones.


Developing with a custom Windshaft version

If you plan or want to use a custom / not released yet version of windshaft (or any other dependency), the best option is to use npm link. You can read more about it at npm-link: symlink a package folder.

$ cd /path/to/Windshaft
$ npm install
$ npm link
$ cd /path/to/Windshaft-cartodb
$ npm link windshaft


We follow SemVer for versioning. For available versions, see the tags on this repository.


This project is licensed under the BSD 3-clause "New" or "Revised" License. See the LICENSE file for details.