diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 6c4e4161..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,11 +0,0 @@ -Contributing ---- - -The issue tracker is at [github.com/CartoDB/Windshaft-cartodb](https://github.com/CartoDB/Windshaft-cartodb). - -We love pull requests from everyone, see [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/#contributing). - - -## Submitting Contributions - -* You will need to sign a Contributor License Agreement (CLA) before making a submission. [Learn more here](https://carto.com/contributions). diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index f5102f3b..00000000 --- a/INSTALL.md +++ /dev/null @@ -1,41 +0,0 @@ -# Installing Windshaft-CartoDB - -## Requirements - -Make sure that you have the requirements needed. These are: - -- Node 10.x -- npm 6.x -- PostgreSQL >= 10.0 -- PostGIS >= 2.4 -- CARTO Postgres Extension >= 0.24.1 -- Redis >= 4 -- libcairo2-dev, libpango1.0-dev, libjpeg8-dev and libgif-dev for server side canvas support -- C++11 (to build internal dependencies if needed) - -### Optional - -- Varnish (http://www.varnish-cache.org) - -## PostGIS setup - -A `template_postgis` database is expected. One can be set up with - -```shell -createdb --owner postgres --template template0 template_postgis -psql -d template_postgis -c 'CREATE EXTENSION postgis;' -``` - -## Build/install - -To fetch and build all node-based dependencies, run: - -```shell -npm install -``` - -Note that the ```npm``` step will populate the node_modules/ -directory with modules, some of which being compiled on demand. If you -happen to have startup errors you may need to force rebuilding those -modules. At any time just wipe out the node_modules/ directory and run -```npm``` again. diff --git a/README.md b/README.md index f6f0bdde..26a8db71 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,87 @@ -Windshaft-CartoDB -================== +# Windshaft-CartoDB [![Build Status](https://travis-ci.org/CartoDB/Windshaft-cartodb.svg?branch=master)](https://travis-ci.org/CartoDB/Windshaft-cartodb) -This is the [CartoDB Maps API](http://docs.cartodb.com/cartodb-platform/maps-api.html) tiler. It extends -[Windshaft](https://github.com/CartoDB/Windshaft) with some extra functionality and custom filters for authentication. +This is the [CartoDB Maps API](http://docs.cartodb.com/cartodb-platform/maps-api.html) tiler. It extends [Windshaft](https://github.com/CartoDB/Windshaft) and exposes a complete web service with extra functionality: -* reads dbname from subdomain and cartodb redis for pretty tile urls -* configures windshaft to publish `cartodb_id` as the interactivity layer -* gets the default geometry type from the cartodb redis store -* allows tiles to be styled individually -* provides a link to varnish high speed cache -* provides a [template maps API](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/Template-maps.md) +* Intantiate [`Anonymous Maps`](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/guides/03-anonymous-maps.md) defined through CARTO's map configuration ([MapConfig](https://github.com/CartoDB/Windshaft/blob/master/doc/MapConfig-specification.md)). +* Create [`Named Maps`](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/guides/04-named-maps.md) based on customizables templates. +* Get map previews through [`Static Maps`](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/guides/05-static-maps-API.md) API. +* Render maps with large amount of data faster using [`Tile Aggregation`](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/guides/06-tile-aggregation.md). +* Build advanced maps with enriched data through [`Analyses Extension`](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/guides/09-MapConfig-analyses-extension.md). +* Fetch tabular data from analysis nodes with [`Dataviews`](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/guides/10-MapConfig-dataviews-extension.md) -Install -------- -See [INSTALL.md](INSTALL.md) for detailed installation instructions. +## Install -Configure ---------- +### Requirements -Create the config/environments/.js files (there are .example files -to start from). You can optionally use the ./configure script for this, -see ```./configure --help``` to see available options. +* Node 10.x +* npm 6.x +* PostgreSQL >= 10.0 +* PostGIS >= 2.4 +* CARTO Postgres Extension >= 0.24.1 +* Redis >= 4 +* libcairo2-dev, libpango1.0-dev, libjpeg8-dev and libgif-dev for server side canvas support +* C++11 (to build internal dependencies if needed) -Look at lib/cartodb/server-options.js for more on config +### Optional -Upgrading ---------- +* [Varnish](http://www.varnish-cache.org) -Checkout your commit/branch. If you need to reinstall dependencies (you can check [NEWS](NEWS.md)) do the following: +### PostGIS setup -```sh -$ rm -rf node_modules -$ npm install +A `template_postgis` database is expected. One can be set up with + +```shell +createdb --owner postgres --template template0 template_postgis +psql -d template_postgis -c 'CREATE EXTENSION postgis;' ``` +### Build + +To fetch and build all node-based dependencies, run: + +```shell +npm ci ``` + +### Run + +Create the `./config/environments/.js` file (there are `.example` files to start from). Look at `./lib/cartodb/server-options.js` for more on config. + +```shell node app.js ``` -Where is the name of a configuration file under config/environments/. +Where `` is the name of a configuration file under `./config/environments/`. -Note that caches are kept in redis. If you're not seeing what you expect -there may be out-of-sync records in there. -Take a look: http://redis.io/commands +## Documentation +The [docs directory](https://github.com/CartoDB/Windshaft-cartodb/tree/master/docs) contains different documentation resources, from higher level to more detailed ones: +The [Maps API](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/Map-API.md) defined the endpoints and their expected parameters and outputs. -Documentation -------------- - -The [docs directory](https://github.com/CartoDB/Windshaft-cartodb/tree/master/docs) contains different documentation -resources, from higher level to more detailed ones: -The [Maps API](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/Map-API.md) defined the endpoints and their -expected parameters and outputs. - - -Examples --------- +### Examples [CartoDB's Map Gallery](http://cartodb.com/gallery/) showcases several examples of visualisations built on top of this. -Contributing ---- +## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md). +The issue tracker: [github](https://github.com/CartoDB/Windshaft-cartodb/issues). + +We love pull requests from everyone, see [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/#contributing). + +### Submitting Contributions + +* You will need to sign a Contributor License Agreement (CLA) before making a submission. [Learn more here](https://carto.com/contributions). ### 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](https://docs.npmjs.com/cli/link.html). - -**Quick start**: +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](https://docs.npmjs.com/cli/link.html). ```shell -~/windshaft-directory $ npm install -~/windshaft-directory $ npm link -~/windshaft-cartodb-directory $ npm link windshaft +$ cd /path/to/windshaft/directory/ +/path/to/windshaft/directory$ npm install +/path/to/windshaft/directory/$ npm link +$ cd /path/to/windshaft-cartodb/directory/ +/path/to/windshaft-cartodb/directory$ npm link windshaft ```