CARTO can be installed on a local server, or set of servers, either directly or using our commercial installer.

Upgrading CARTO Builder

Pre-upgrade

Make a full backup

In order to make your upgrade as safe as possible, we encourage you to make a full backup of your CARTO onpremises install, and to double-check it is working. If at all possible, make a full snapshot of your machine or data volume.

Please check backuprecovery for common backup instructions.

Check installed and upgrade version

You can check which version of CARTO onpremises is installed using this command:

1
head /etc/carto-builder.config | grep CARTO_VERSION

You can check the upgrade pack version in the builder installer file name:

1
carto-builder-<version>-rhel-6-x86_64.tar.gz

Check if your version is upgradeable

2.1.0 -> 2.1.x

Every CARTO 2.1.x onpremises version can be upgraded to every greater 2.1.x version.

2.1.x -> 2.2.x

Every CARTO 2.1.x onpremises version can be upgraded to every other 2.2.x version

2.2.x -> 3.0.0

Every CARTO 2.2.x onpremises version can be upgraded to every other 3.0.0 version

Warning
2.2.x -\> 3.x.x is a major upgrade and next steps need to be followed carefully in order to prepare the upgrade. (if doing a Multi Host Upgrade these steps must be executed for the `postgresql` role only).

1) These python packages must be installed:

  • ansible >= 2.7.0
  • psycopg2 >= 2.7.5

You can install those packages by issuing a single command to your current install:

1
sudo /opt/carto/postgresql/embedded/bin/pip install --upgrade setuptools && sudo /opt/carto/postgresql/embedded/bin/pip install --upgrade pip && sudo /opt/carto/postgresql/embedded/bin/pip install --upgrade ansible==2.7.0 psycopg2==2.7.5

2) Unpack the tar.gz file of the builder installer:

1
tar xfz carto-builder-<version>-rhel-6-x86_64.tar.gz

Where <version> is the version of the file provided.

3) PostgreSQL should be upgraded BEFORE executing the CARTO onprem installer:

1
2
cd carto-builder-<version>-rhel-6-x86_64
sudo ./postgresql-upgrade.sh
Warning
Please do not run the `postgresql-upgrade.sh` script more than once. In case it fails, please contact CARTO in order to receive support for upgrading.
Note
Please continue with all remaining steps in order to upgrade your install.
3.0.x -> 3.0.x

Every CARTO 3.0.x onpremises version can be upgraded to every other 3.0.x version

Check disk space

The upgrade process takes a snapshot of your current configuration and data. It is advisable to check if you have enough disk space for this operation to avoid possible incoherent upgrades due to lack of disk space.

Single Host Upgrade

The CARTO installer artifact can be used to upgrade from a previous compatible running version.

1) Unpack the tar.gz file of the Builder installer

1
tar xfz carto-builder-<version>-rhel-6-x86_64.tar.gz

Where version is the version of the file provided.

Note
When upgrading, the installer artifact's configuration parameters won't get applied to the existing configuration in order to not interfere with existing customizations.

2) In order to upgrade, run the installer, with sudo (or as root):

1
2
cd carto-builder-<version>-rhel-6-x86_64
sudo ./carto-setup.sh builder
Note
In order to provide an additional security layer, the installer will take a snapshot of your current configuration. During that process, if something goes wrong, the upgrade will restore the snapshot it took and leave your installation as it was before doing the upgrade. During this process the installer may appear unresponsive.

After-upgrade steps

Enable create_overviews feature flag

After upgrading from CARTO onpremises 2.1.x to 2.2.x it is mandatory to enable create_overviews feature flag for all existing users. In order to do so, please execute:

1
carto-builder-feature-flags.sh enable all create_overviews
OAuth tokens: CARTO_VERSION >= 3.0.1

If upgrading to a version >= 3.0.1, and you use Oauth, please make sure you create a cron job to periodically clean the expired Oauth tokens postinstallconfig

Multi Host Upgrade

Warning
Multi host upgrade is still under heavy development and should not be considered production ready. Some common capabilities, such as upgrades or backups, are not yet finalized and will require some system administration skills and manual interaction. You are welcome to test it in a safe development environment and send us feedback.

The CARTO installer artifact can be used to setup CARTO in a fresh, installed Red Hat server or to upgrade from a previous compatible running version. Please refer to Pre upgrade for an upgradeable version list.

1) Unpack the tar.gz file of the builder installer

1
tar xfz carto-builder-<version>-rhel-6-x86_64.tar.gz

Where {version} is the version of the file provided.

Note
When upgrading, the installer artifact's configuration parameters won't get applied in order to not interfere with existing customizations, so remember that any changes made to the install configuration file will not be applied, and the current ones will prevail. Please refer to the install documentation for further reference.

2) Run the installer, with sudo (or as root):

1
2
cd carto-builder-<version>-rhel-6-x86_64
sudo ./carto-setup.sh builder <server_role>
Note
Current available roles are: redis, postgresql, sql-api, windshaft, builder, resque, varnish and nginx

Upgrade Roles in Different Instances

CARTO Builder can also be installed in different instances, separated per role. The idea behind this is to be able to run just one service at a time, in every instance, instead of everything together. This allows you to separately maintain and upgrade different roles and enables you to scale certain parts of the platform.

There are currently eight roles to upgrade: redis, postgresql, sql-api, windshaft, builder, resque, varnish and nginx.

Each role must be upgraded in a specific order. Each role includes the following dependencies:

  • Redis. It does not depend on any other role.
  • PostgreSQL. It does not depend on any other role.
  • SQL API. It depends on redis and postgresql.
  • Windshaft (Maps API). It depends on redis, postgresql and sql-api.
  • Varnish. It does not depend on any other role.
  • BUILDER. It depends on redis, postgresql, varnish and windshaft.
  • Resque. It depends on builder, postgresql, varnish and windshaft. Note that the configuration requirements for this role are the same as Builder. Although this role requires that Builder has been installed previously, it does not need to connect to the Builder instance.
  • Nginx. It depends on builder, sql-api, varnish and windshaft.

Step by Step Installation Guide

This section includes all the required commands to upgrade one role per host. It is also possible to upgrade several roles on the same host by providing the role list to the installer.

As explained in the previous section, the order of installing roles matters.

  1. upgrade redis role host:

    1
    
    sudo ./carto-setup.sh builder redis
    
  2. Install postgresql role host:

    1
    
    sudo ./carto-setup.sh builder postgresql
    
  3. Install sql-api role host:

    1
    
    sudo ./carto-setup.sh builder sql-api
    
  4. Install windshaft role host:

    1
    
    sudo ./carto-setup.sh builder windshaft
    
  5. Install varnish role host:

    1
    
    sudo ./carto-setup.sh builder varnish
    
  6. Install builder role host:

    1
    
    sudo ./carto-setup.sh builder builder
    
  7. Install resque role host:

    1
    
    sudo ./carto-setup.sh builder resque
    
  8. Install nginx role host:

    1
    
    sudo ./carto-setup.sh builder nginx
    

In order to upgrade more than one role per host:

1
sudo ./carto-setup.sh builder varnish,nginx