How to configure basemaps in CartoDB

The way to add/change the basemaps available in CartoDB is chaging the config/app_config.yml. Basically you need to add a new entry called basemaps, that entry can have different sections and each section one or more basemaps.

Each section corresponds to row in CartoDB basemap dialog. If the basemaps entry is not present a set of default basemaps will be used (CartoDB and Stamen ones, check the default basemaps file https://github.com/CartoDB/cartodb/blob/master/lib/assets/javascripts/cartodb/table/default_layers.js)

Also, it's always necessary to have a default basemap among all the confifured ones in the app_config.yml. The way to set a basemap as default a "default" attribute needs to be added to the basemap. There can be several basemaps in the config with the attribute default set, however, only the first one found in the same order than in the app_config will be used as default.

an example config:

basemaps:
    CartoDB:
      positron_rainbow:
        default: true
        url: 'http://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png' 
        subdomains: 'abcd' 
        minZoom: '0' 
        maxZoom: '18' 
        name: 'Positron' 
        className: 'positron_rainbow' 
        attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors © <a href= "http://cartodb.com/attributions#basemaps">CartoDB</a>' 
      dark_matter_rainbow:
        url: 'http://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png' 
        subdomains: 'abcd' 
        minZoom: '0' 
        maxZoom: '18' 
        name: 'Dark matter' 
        className: 'dark_matter_rainbow' 
        attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors © <a href="http://cartodb.com/attributions#basemaps">CartoDB</a>' 
      positron_lite_rainbow:
        url: 'http://{s}.basemaps.cartocdn.com/light_nolabels/{z}/{x}/{y}.png' 
        subdomains: 'abcd' 
        minZoom: '0' 
        maxZoom: '18' 
        name: 'Positron (lite)' 
        className: 'positron_lite_rainbow' 
        attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors © <a href="http://cartodb.com/attributions#basemaps">CartoDB</a>' 
      
    stamen:
      toner_stamen:
        url: 'https://stamen-tiles-{s}.a.ssl.fastly.net/toner/{z}/{x}/{y}.png' 
        subdomains: 'abcd' 
        minZoom: '0' 
        maxZoom: '18' 
        name: 'Toner' 
        className: 'toner_stamen' 
        attribution: 'Map tiles by <a href="http://stamen.com">Stamen Design</a>, under <a href="http://creativecommons.org/licenses/by/3.0">CC BY 3.0</a>. Data by <a href="http://openstreetmap.org">OpenStreetMap</a>, under <a href="http://www.openstreetmap.org/copyright">ODbL</a>.' 
      

Basemaps with a layer of labels

Basemaps can optionally add a layer with labels on top of other layers. To do so, you should add the labels key to the basemap config, as follows:

positron_rainbow:
  default: true
  url: 'http://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png' 
  subdomains: 'abcd' 
  minZoom: '0' 
  maxZoom: '18' 
  name: 'Positron' 
  className: 'positron_rainbow' 
  attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors © <a href= "http://cartodb.com/attributions#basemaps">CartoDB</a>' 
  labels:
    url: 'http://{s}.basemaps.cartocdn.com/light_only_labels/{z}/{x}/{y}.png'