Switch branches/tags
0.13.1 1-fix-sql-bug 1.0 2.0 3.11.X 3.12.3-dani 4.0.x-new 4.1.x 4.1.x.2 4.11.113 54-split-size-color--color-specs 54-split-size-color--editor-fields-fixes 640-update-DI-dependency 1000x 1399-hide-autostyle-histogram-button 1610DoNotPrependUsernameToColumnsInEditor 1772-support-fix-large-dataset-list 1997-add-missing-properties-to-events 2148-fix-vulnerabilities 2192NoisyPrivacyChangeMessage 2205DoNotExportDupVizs 2205RemoveDupTableVizs 2220DoNotExportInvalidAssets 2282ExporAndImportNamedMaps 2289DoNotAbortMigrationIfApiKeyQueriesFail 4314-round-zoom-level 11726-escape-prefixes-and-sufixes 11876-improve-onboarding-for-empty-layer 12549-Validate_if_layer_source_exists_when_layer_has_changed 12958-controlled-dataset-creation 12980-carto.geopkg-import-export-tech 12990-add-carto-api-client 13130-fix-statics-pages-generator 13308-fix-analysis-button-alignment 13336-add-credentials-to-cors-enabled-hosts 13478-wrong-user-flow-layer 13642-sql-messages 13683-add-default-point-aggregation 13683-test-default-point-aggregation 13785-popup-management 13844MigrateNotifications 14081-deprecate-twitter-connector-again 14129-missing-color-ramps 14313-map-button-tests 14314-datasets-store 14315-quick-actions-modals 14318-bulk-actions 14321-datasets-filtering 14325-global-search-backend 14333-forgot-password 14336_mfa_login 14346-dataset-component 14346-fake-map-card 14346-feature-dropdown 14346-filter-dropdown 14346-pagination 14346-user-dropdown 14353-setup-maps 14372-order-by-favorited 14424-datasets-usage 14425_mfa_meets_eumapi 14430-number-views 14461-home-your-maps 14476-fix-pagination 14482-locked-count 14493_sync_oauth_apps 14509-reactivate-mfa 14513-fix-dataset-public-link 14518-silent-flow-error 20181108-test-new-dashboard FixPermissionsRake WIP-frozen-editor-assets-back WIP_frozen-editor-assets add-chart-of-limits add-eslint-rules add-pr-template appcues automatic_version_diagnosis bq-connector c1981_and_13127-wayfinding_mixed carto-js-4-1-1 copy dashboard-karma-tests developer-center-dataservices-api-key developer-center-new-guides developer-center-wrong-reference-importapi developer-center difficult_layer_names dot-properties es6-preset ext_024 fallback-reference fix-authapi-margins fix-clustering-analysis-typo fix-shrinkwrap-protocol-changes force-delete-api-key forgot-password-migration forms-no-auto-fill frozen-editor-assets-back frozen-editor-assets-only-back gtm-fix help-contact-form improve-geocoding-routing-replace-stacklayout improve-reload jferzoco_buffer_limits_edit join leaflet1.3.1 leapfrog-buble leapfrog-di-typescript leapfrog-module-of-every-view leapfrog-virtualdom map-card-component mapnik-reference-dot master metadata_only_migration migrate-to-npm5 mobile_apps_dashboard multiple-clients naming-fixes navigation-bar-and-more new-dashboard-browsers-fixes new-dashboard-data-hotfixes new-dashboard-feature new-dashboard-vue-test new-homepage nodejs-10 oauth-dataset-apikey oauth-dataset-revoke oauth-dataset-role oauth-migration oauth_master_key onpremises-2.2.x overviews-deprecation react-views release/lorenzo remove-old-code render-map-after-initialization retina revert-13614-mobile_apps_dashboard revert-profile_account-FF-removal s991 schema_public_user send-private-events setup-hound-stylelint support-915 support1566-fix-legends-margins support1724-imgbutton support1724 tangram-platform-limits-show-error-tiles test-autostyle test-leaflet-fix use-webpack-sass viz-order-and-direction-2 yarn-addition
Nothing to show
Find file Copy path
406 lines (217 sloc) 11.1 KB



CARTO works with Ubuntu 16.04 x64. This documentation describes the process to install CartoDB in this specific OS version.

However this doesn't mean that it won't work with other Operating Systems or other Ubuntu. There are also many successful installations on Amazon EC2, Linode, dedicated instances and development machines running OS X and Ubuntu 12.04+.

You will find notes along this guide explaining some of the Ubuntu 16.04 specifics, and pointing to alternative solutions for other environments.

System requirements

Besides the OS version mentioned in the introduction, there are some system requirements needed before starting with the installation of the stack. Also this process assumes that you have enough permissions in the system to run successfully most part of the commands of this doc.

System locales

Installations assume you use UTF8. You can set the locale by doing this:

sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

Build essentials

Although we try to maintain packaged versions of almost every part of the stack, there are some parts like gems or npm packages that need some development tools in the system in order to compile. You can install all the needed build tools by doing this:

sudo apt-get install make pkg-config


You will need git commands in order to handle some repositories and install some dependencies:

sudo apt-get install git



CARTO requires PostgreSQL 10+. The PPA packages also provide some additional patches, which are not needed but help improve the experience in production environments.

  • Add PPA repository

    sudo add-apt-repository ppa:cartodb/postgresql-10 && sudo apt-get update
  • Install packages

    sudo apt-get install postgresql-10 \
                         postgresql-plpython-10 \

PostgreSQL access authorization is managed through pg_hba.conf configuration file, which is normally in /etc/postgresql/10/main/pg_hba.conf. Here it's defined how the users created in postgresql cluster can access the server. This involves several aspects like type of authentication (md5, no password, etc..) or source IP of the connection. In order to simplify the process of the installation we are going to allow connections with postgres user from localhost without authentication. Of course this can be configured in a different way at any moment but changes here should imply changes in database access configuration of CARTO apps.

Edit /etc/postgresql/10/main/pg_hba.conf, modifying the existing lines to use trust authentication (no password access from localhost):

local   all             postgres                                trust
local   all             all                                     trust
host    all             all               trust

For these changes to take effect, you'll need to restart postgres:

sudo systemctl restart postgresql
  • Create some users in PostgreSQL. These users are used by some CARTO apps internally

    sudo createuser publicuser --no-createrole --no-createdb --no-superuser -U postgres
    sudo createuser tileuser --no-createrole --no-createdb --no-superuser -U postgres
  • Install CartoDB postgresql extension. This extension contains functions that are used by different parts of the CartoDB platform, included Builder and the SQL and Maps API.

    git clone
    cd cartodb-postgresql
    git checkout <LATEST cartodb-postgresql tag>
    sudo make all install

GIS dependencies

  • Add GIS PPA

    sudo add-apt-repository ppa:cartodb/gis && sudo apt-get update
  • Install GDAL

    sudo apt-get install gdal-bin libgdal-dev



CARTO requires PostGIS 2.4. The PPA just packages this version for Ubuntu 16.04.

  • Install PostGIS

    sudo apt-get install postgis
  • Initialize template postgis database. We create a template database in postgresql that will contain the postgis extension. This way, every time CartoDB creates a new user database it just clones this template database

    sudo createdb -T template0 -O postgres -U postgres -E UTF8 template_postgis
    psql -U postgres template_postgis -c 'CREATE EXTENSION postgis;CREATE EXTENSION postgis_topology;'
    sudo ldconfig
  • (Optional) Run an installcheck to verify the database has been installed properly

    sudo PGUSER=postgres make installcheck # to run tests

    Check for further reference



CARTO requires Redis 4+. You can also optionally install redis-cell for rate limiting, which is not described by this guide.

  • Add redis PPA

    sudo add-apt-repository ppa:cartodb/redis-next && sudo apt-get update
  • Install redis

    sudo apt-get install redis


By default redis server is configured to only have periodic snapshotting to disk. If stopped or restarted some data stored in redis since the last snahpshot can be lost. In CARTO redis is not just a simple cache storage. It stores information that need to be persisted.

For data safety, make sure to have proper values of save, appendonly and appendfsync config attributes. For more information check


Node.js is required by different parts of the stack. The more significant are the Maps and SQL APIs. It's also used to install and execute some dependencies of Builder.

  • Add the PPA

    sudo add-apt-repository ppa:cartodb/nodejs && sudo apt-get update
  • Install Node.js

    sudo apt-get install nodejs

    Note this should install both Node.js 6.9.2 and npm 3.10.9. You can verify the installation went as expected with:

    nodejs -v
    npm -v


CARTO uses Node.js v6.9.2 and npm 3.10.9. You must use these precise versions to avoid problems.

We will also install some development libraries that will be necessary to build some Node.js modules:

sudo apt-get install libpixman-1-0 libpixman-1-dev
sudo apt-get install libcairo2-dev libjpeg-dev libgif-dev libpango1.0-dev


  • Download API

    git clone git://
    cd CartoDB-SQL-API
  • Install npm dependencies

    npm install
  • Create configuration. The name of the filename of the configuration must be the same than the environment you are going to use to start the service. Let's assume it's development.

    cp config/environments/development.js.example config/environments/development.js
  • Start the service. The second parameter is always the environment if the service. Remember to use the same you used in the configuration.

    node app.js development


  • Download API

    git clone git://
    cd Windshaft-cartodb
  • Maps API dependencies are managed using yarn. Install it:

    sudo npm install -g yarn@0.27.5
  • Install yarn dependencies

    yarn install
  • Create configuration. The name of the filename of the configuration must be the same than the environment you are going to use to start the service. Let's assume it's development.

    cp config/environments/development.js.example config/environments/development.js
    mkdir logs
  • Start the service. The second parameter is always the environment of the service. Remember to use the same you used in the configuration.

    node app.js development



CARTO requires exactly Ruby 2.2.x. Older or newer versions won't work.

  • Add brightbox ruby repositories

    sudo apt-add-repository ppa:brightbox/ruby-ng && sudo apt-get update
  • Install ruby 2.2

    sudo apt-get install ruby2.2 ruby2.2-dev
  • Install bundler. Bundler is an app used to manage ruby dependencies. It is needed by CARTO Builder

    sudo apt-get install ruby-bundler
  • Install compass. It will be needed later on by CARTO's Builder

    sudo gem install compass



CARTO users Python 2.7+. Python 3 will not work correctly.

  • Download Builder's code

    git clone --recursive
    cd cartodb
  • Install pip

    sudo apt-get install python-pip
  • Install ruby dependencies

    sudo apt-get install imagemagick unp zip libicu-dev
    RAILS_ENV=development bundle install
  • Install python dependencies

    sudo pip install --no-use-wheel -r python_requirements.txt


If this fails due to the installation of the gdal package not finding Python.h or any other header file, you'll need to do this:

export CPLUS_INCLUDE_PATH=/usr/include/gdal
export C_INCLUDE_PATH=/usr/include/gdal
export PATH=$PATH:/usr/include/gdal

After this, re-run the pip install command. Variables can be passed to sudo if exporting them and re-running pip install doesn't work:

sudo CPLUS_INCLUDE_PATH=/usr/include/gdal C_INCLUDE_PATH=/usr/include/gdal PATH=$PATH:/usr/include/gdal pip install --no-use-wheel -r python_requirements.txt

If gdal keeps failing, see more information here:

  • Install Node.js dependencies

    npm install
  • Compile static assets

    npm run carto-node && npm run build:static
  • (Optional) Precompile assets. Needed if you don't want to use CARTO's CDN for assets.

    export PATH=$PATH:$PWD/node_modules/grunt-cli/bin
    bundle exec grunt --environment=development
  • Create configuration files

    cp config/app_config.yml.sample config/app_config.yml
    cp config/database.yml.sample config/database.yml
  • Start the redis-server that allows access to the SQL and Maps APIs:

    sudo systemctl start redis-server
  • Initialize the metadata database

    RAILS_ENV=development bundle exec rake db:create
    RAILS_ENV=development bundle exec rake db:migrate
  • Start Builder's HTTP server

    RAILS_ENV=development bundle exec rails server
  • In a different process/console start the resque process

    RAILS_ENV=development bundle exec ./script/resque