On-Premises Private

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 release of CARTO onpremises is installed using this command:

1
2
3
4
5
6
7
8

/opt/carto/tools/bin/cartoctl config -cr

+---------------------------------------+
|                 ROLES                 |
+---------------------------------------+
| builder                               |
|   release:                            |
|     version = 4.1.0                   |

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

1

carto-builder-<version>-rhel-7-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

3.0.x -> 4.0.0

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

Warning
3.0.x -\> 4.0.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).
Warning
4.0.x version deprecates the configuration file `/etc/carto-builder.conf` in favor of `~/.carto/config.yml`.
Warning
4.0.x version deprecates `carto-setup.sh` installer, in favor of `cartoctl`.
Warning
4.0.x version requires at least RHEL7/CentOS 7 linux distribution with systemd.

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

1

tar xfz carto-builder-<version>-upgrade-rhel-7-x86_64.tar.gz

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

2) Migrate configuration

Note
For reference about how the new configuration file `~/.carto/config.yml` looks like, please check the builder\_installation section.
Note

It is required to transfer a backup from the old On-Premise installation to the new one of RHEL7/CentOS 7. Folders that should be copied:

  • PostgreSQL data that is stored in a folder called postgresql under the path defined by CARTO_DATA_ROOT_PATH.
  • Builder data that is stored in the folder called shared under the path defined by CARTO_DATA_ROOT_PATH.

This two folders can be stored anywhere on the new instance, except in a folder under the path defined by the new environment variable CARTO_POSTGRES_DATA_ROOT_PATH.

1
2
3
4

cd carto-builder-<version>-upgrade-rhel-7-x86_64
ln -sf path_to_postgresql_backup upgrade/pg_backup
ln -sf path_to_builder_backup upgrade/shared_backup
sudo ./cartoctl init -l license.lic
Warning
Since `carto-builder.conf` version has been deprecated in favor of `~/.carto/config.yml`, please edit the new config file and modify it accordingly. 
1

vi ~/.carto/config.yml

3) Perfom the upgrade

Warning
Beyond this point, database data might be lost or corrupted. Please, make sure to perform a **backup** before. The data available at upgrade/pg\_backup and upgrade/shared\_backup (the symlinks you just created in the previous step) will be overrwritten by the upgrade process so make sure you have another copy safely stored elsewhere. 
1
2

cd carto-builder-<version>-upgrade-rhel-7-x86_64
sudo ./cartoctl nodes install
Note
For a multihost installation, reinstalling the rest of the nodes once the postgresql one is upgraded, is **mandatory**.
4.0.0 -> 4.0.1

CARTO 4.0.0 onpremises version can be upgraded to 4.0.1 version.

1
2
3
4

tar xfz carto-builder-4.0.1-rhel-7-x86_64.tar.gz
cd carto-builder-4.0.1-rhel-7-x86_64
sudo ./cartoctl tasks import tasks/upgrade/4.0.1
sudo ./cartoctl nodes upgrade
Warning
CARTO services will be restarted during the upgrade process.
4.0.1 -> 4.1.0
Note
Telemetry is enabled by default from `4.1.0` version onwards. We gather different metrics to understand how the product is being used and be able to improve it. We can also help you understand how CARTO is being used in your organization, using these metrics. We don't collect user's data, or any kind of personal data. To disable telemetry in your CARTO installation, please refer to disabletelemetry instructions.

CARTO 4.0.1 onpremises version can be upgraded to 4.1.0 version.

1
2
3
4

tar xfz carto-builder-4.1.0-rhel-7-x86_64.tar.gz
cd carto-builder-4.1.0-rhel-7-x86_64
sudo ./cartoctl tasks import tasks/upgrade/4.1.0
sudo ./cartoctl nodes upgrade
Warning
CARTO services will be restarted during the upgrade process.

Release 4.1.0 brings in the new platter service, which was not available in previous releases and is part of the new Telemetry feature.

To have platter installed, simply execute the following from the release root folder:

1
2

cd /carto-builder-4.1.0-rhel-7-x86_64
sudo ./tasks/upgrade/4.1.0/scripts/install_platter.sh
4.1.0 -> 4.2.0

CARTO 4.1.0 onpremises version can be upgraded to 4.2.0 version.

Warning
4.1.0 -\> 4.2.x requires a major postgresql version upgrade. 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.
Warning
For a multihost upgrade, these steps must be executed for the `postgresql` role only
  1. Unpack the tar.gz file of the builder installer and import 4.2.0 upgrade tasks
1
2
3

tar xfz carto-builder-4.2.0-rhel-7-x86_64.tar.gz
cd carto-builder-4.2.0-rhel-7-x86_64
sudo ./cartoctl tasks import tasks/upgrade/4.2.0
  1. Execute postgresql pre upgrade tasks
1

sudo ./cartoctl nodes tasks exec -r postgresql postgresql_preupgrade_4.2.0

3) Perfom the upgrade

Warning
Beyond this point, database data might be lost or corrupted. Please, make sure to perform a **backup** before. 
1

sudo ./cartoctl nodes upgrade
Note
For a multihost installation, upgrading the rest of the nodes once the postgresql one is upgraded, is **mandatory**.

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-7-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 not to interfere with existing customizations.

2) Import upgrade tasks, corresponding to the version we are going to upgrade to:

1
2

cd carto-builder-<version>-rhel-7-x86_64
sudo ./cartoctl tasks import tasks/upgrade/<version>

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

1
2

cd carto-builder-<version>-rhel-7-x86_64
sudo ./cartoctl nodes upgrade
Warning
CARTO services will be restarted during the upgrade process.

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

Note
If you are running a `>= 4.0.0` version, this is not necessary and will be automatically handled as a systemd timer.