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

Backup and Recovery with CARTO LDS On-Premises

It is possible (and strongly recommended) to perform periodical backups of CARTO LDS On-Premises. This will allow you to recover both data, and configurations, in case of disaster.

Two scripts have been provided for these tasks. Unless your sudo configuration allows you to load commands from onpremises paths loaded, these scripts are not going to work properly under sudo. To ensure that they work correction, run them directly as root.


This tool will not check if there is enough disk space to host the entire backup. The server should have (in the configured backup path) at least the same disk space used for the data (the default /data) directory.

carto-builder-backup.rb - It offers two methods for creating a backup: rsync and tar. Backups take everything under CARTO_DATA_PATH and store it in CARTO_BACKUP_PATH directory. The script has the ability to check if this is a mount point backup; which are done to an external drive, e.g network drive.

Backups will be created where the $CARTO_BACKUP_PATH variable has been defined in the config file (By default, Builder goes to /backup). Depending on the backup method chosen, the following scenarios may apply:


If rsync is chosen, there should be a backup directory (e.g /backup/production) that will be updated every time that the script is run.


If tar is chosen, there should be a separate tar file every time the backup script is run.

By default, backups are not performed automatically. The user is responsible for running the backup task periodically in cron, or any other method.

The following usage example describes how a backup script is applied:

Usage: carto-dataservices-backup [options]
    -c, --check-mount                Check if backup dir is a mount point
    -r, --redis-retries=val          Retries to check Redis backup completed
    -m, --method=val                 Backup method: rsync (default) or tar
    -h                               Shows this message

The script does not require any parameters in order to run. By default, the script performs a rsync backup in /backup/production.


carto-builder-restore-backup.rb stops all services, takes a backup as generated by carto-builder-backup.rb tool, restores it into CARTO_DATA_PATH, and starts all services. By default, it tries to keep whatever CARTO_DATA_PATH had unless told otherwise. Two different inputs can be provided:

  • A directory (made using rsync method). Make sure that a valid directory is given. For example, if $CARTO_BACKUP_PATH is the backup, the directory that contains the rsync contents will be /backup/production
  • A tar.gz file

The following usage example describes how a backup restore script is applied:

Usage: carto-dataservices-restore-backup [options]
    -d, --rsync-dir=val              Rsync'ed dir to restore
    -f, --tar-file=val               Tar file to restore
    -r, --remove-data-dir            Removes data dir. We keep it by default
    -h                               Shows this message

It is required to pass either option -d or option -f.

The following example comes from the restore of a dataservices installation, from a directory backup created with backup script:

$ carto-dataservices-restore-backup.rb -d /backup/production/
2016-12-09 10:55:14 UTC - DEBUG - Running command [source /opt/carto/dataservices-tools/embedded/lib/../carto/carto-onpremises-lib  dataservices; echo $CARTO_DATA_PATH]

This script is going to restore /backup/production/
into /data/production local data dir. If data dir exists, it will try
to keep it unless you have asked explicitly to not do it.

Please ensure the backup comes from carto-backup.rb script in an unaltered form, or things will not work as expected.

Do you want to proceed? (y/N)y
2016-12-09 10:55:32 UTC - INFO - /opt/carto/dataservices-tools/embedded/bin/carto-dataservices-restore-backup.rb starts

In order to restore a server using a backup, the cleanest approach would be to install the product using the installer for the version. Then use the restore script with the latest backup.