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

Technical Operations with CARTO BUILDER On-Premises

There are many things in CARTO that can be configured, but are not included in the installation process. One way to configure some of these things is by running some specific application tasks.

All tools in Builder tools dir are installed in /opt/carto/builder-tools/embedded/bin

All the operation tools must be executed with root user or full root privileges.

Setup SSL

By default, CARTO On-Premises has a self-signed SSL certificate for the default installation domain (carto.lan). We strongly recommend that before releasing CARTO On-Premises to production, the user loads a real SSL certificate (that is valid for the domain) that will be used in the On-Premises.

First and foremost, the SSL certificates must fulfill the following requirements:

  • We only support SSL certificates without passphrase.
  • We expect the SSL certificate to use two file formats: private key + certificate.
  • Once you have a valid SSL certificate, use the tool:
2 nginx.crt nginx.key
SSL certificate successfully installed

This tool checks that it is a valid SSL certificate, installs the files, and restarts the web server.

Create a new CARTO Organization

When CARTO On-Premises is installed, an organization with an administrator user role is created. Once the setup is complete, you can create new organizations using the tool. For example:

4 --admin-user org-admin \
                                       --password pass \
                                       --email \
                                       --name org-name

The following confirmation message appears org-name organization successfully created.

Additionally, the default organization disk quota (1TB) and the number of seats (100) can be modified:

6 --admin-user org-admin \
                                       --password pass \
                                       --email \
                                       --name org-name \
                                       --seats 200 \
                                       --disk-quota 2097152

The following confirmation message appears org-name organization successfully created

This will create an organization with 2TB of disk space and 200 allowed seats.

Toggle Feature Flags

Feature flags are an advanced CARTO setting and shouldn't be changed unless installing/upgrading instructions or a CARTO representative tells you to do so.

CARTO uses feature flags, so different users can have access to different features. If you need to enable or disable feature flags to one or all users, you can use our feature flag management script, p.e. for enabling carto_overviews for all users:

1 enable all carto_overviews

Please refer to the tool’s help command to know more.

Configure LDAP

It is possible to authenticate in a CARTO organization by using a third-party LDAP server. OpenLDAP and Active Directory are supported. When LDAP is enabled, CARTO BUILDER attempts to authenticate against the configured LDAP server. If the authentication does not work, it fallbacks to the CARTO local users database.

LDAP settings can be configured using tool.

The following is an example config for Windows Active Directory:

11 --host \
                      --port 389 \
                      --connection-user CN=Administrator,CN=Users,DC=carto,DC=com \
                      --connection-password <ADMINISTRATOR_PASSWORD> \
                      --domain-bases OU=cartousers,DC=cartodb,DC=com \
                      --user-id-field sAMAccountName \
                      --username-field sAMAccountName \
                      --email-field userPrincipalName \
                      --user-object-class user \
                      --group-object-class group \
                      --organization-name <ORGANIZATION_NAME>

Configuration Parameters

  • host: IP or hostname of the LDAP server
  • port: Port of the LDAP server
  • connection-user: Full CN of the user to use to connect to the server. e.g: CN=Administrator,CN=Users,DC=carto,DC=com
  • connection-password: Password of the previous user
  • domain-bases: Path to search for users e.g: OU=cartousers,DC=carto,DC=com. You can specify multiple bases separated by ||
  • user-if-field: Name of the LDAP attribute that stores the login name of the user. e.g: sAMAccountName
  • username-field: Name of the LDAP attribute that store the display name of the user. e.g: sAMAccountName
  • email-field: Name of the LDAP attribute that stores the email of the user. e.g: userPrincipalName or mail
  • user-object-class: Class name for users. e.g: user
  • group-object-class: Class name for groups. e.g: group
  • organization-name: The name of the CARTO organization that you want to activate LDAP authentication for

Configure SAML

It is possible to authenticate in a CARTO organization by using a third-party SAML Identity Provider (IdP) service. In this scenario, Builder acts as a Service Provider (SP). When SAML is enabled, CARTO Builder attempts to authenticate against the configured SAML IdP.

SAML settings can be configured using tool. You can configure Builder parameters using the IdP metadata file, or manually add configurations.

Configuration through SAML Metadata File

The metadata file can be configured locally, or through the server corresponding URL location, as follows:

3 --organization-name "organization"
                      --saml-email-attribute "username"
                      --saml-idp-metadata-file http://test-saml.cartodb.lan/simplesaml/saml2/idp/metadata.php

Manual Configuration

SAML IdP properties can be configured manually, as follows:

4 --organization-name "organization"
                      --saml-email-attribute "username"
                      --saml-idp-sso-target-url "http://test-saml.cartodb.lan/simplesaml/saml2/idp/SSOService.php"
                      --saml-idp-cert-fingerprint "10:F7:56:E7:5E:6D:87:2B:15:46:8F:6C:04:14:FC:C8:6B:02:D6:6B"

Configuration Parameters

  • organization-name: Name of the organization, e.g., orgname. Required.
  • saml-email-attribute: Attribute with the user email, e.g., email. Required.
  • saml-idp-metadata-file: Url or file that contains metadata about the IdP, e.g., Optional, if not given, we’‘ll enter in manual configuration mode.
  • saml-issuer: Name of the service provider in the SAML server. Optional. It defaults to https://<domain>/user/orgname/saml/metadata where <domain> is the value of CARTO_DOMAIN in your config file.
  • saml-idp-sso-target-url: SAML Identity Provider login URL, e.g., Required on manual configuration
  • saml-idp-slo-target-url: SAML Identity Provider logout URL, e.g., Optional.
  • saml-idp-cert-fingerprint: SAML server certificate fingerprint, e.g., 8C:47:97:B1:E2:E4:6C:06:B5:56:11:8A:5A:8B:53:5C:01:05:CB:05 Required on manual configuration
  • saml-assertion-consumer-service-url: CARTO URL for SAML, including organization name e.g., Optional. It defaults to the URL built from configuration and organization name
  • saml-single-logout-service-url: CARTO URL for SAML logout, including organization name, e.g., Optional. It defaults to the URL built from configuration and organization name
  • saml-name-identifier-format Format of the name identifier parameter, e.g., urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified. Optional. It defaults to urn:oasis:names:tc:SAML:2.0:nameid-format:transient

Configure Kerberos

It is possible to authenticate a CARTO organization by using Kerberos by configuring a webserver, as an HTTP service principal, that will handle the authentication for Builder. You will need a keytab file that has the service principal name for the Builder On-Premises installation that is reachable through https://onpremises.devnet.local; where onpremises is the name of the CARTO organization and Kerberos realm DEVNET.LOCAL is the keytab that we would have generated in Kerberos KDC server and contains entries with different encryptions, such as (example using ktutil tool)

$ ktutil
ktutil:  read_kt ./http.keytab
ktutil:  list
slot KVNO Principal
---- ---- ---------------------------------------------------------------------
1    3 HTTP/onpremises.devnet.local@DEVNET.LOCAL
2    3 HTTP/onpremises.devnet.local@DEVNET.LOCAL
3    3 HTTP/onpremises.devnet.local@DEVNET.LOCAL
4    3 HTTP/onpremises.devnet.local@DEVNET.LOCAL

The next step is to configure On-Premises using the tool. The following example assumes a keytab file called http.keytab and the DEVNET.LOCAL realm.

multiple\_hosts Remember to execute `` in all the servers with nginx or builder roles.
1 enable --keytab-file http.keytab --realm DEVNET.LOCAL

Important note: The CARTO_USER name set at installation time in the carto-builder.config is the user you can authenticate with when Kerberos is disabled and must not be a user present in Kerberos.

ArcGIS connector

ArcGIS connector is disabled on installation, but it can be enabled at any time.

1 enable

Use the keyword disable to disable it

Enabling auth_api feature

Auth API should be enabled for new installations. When upgrading from a CARTO onpremises version < 2.2.1, you should run this script to enable it:


Enable OAuth logging using third party providers

An organization owner may want to allow users to signup/login using credentials of third party providers such as Github or Google. This feature is enabled in the organization’s admin panel but for the feature to work correctly we need to add <client_id> and <client_secret> of the provider to the system. currently Google and Github are supported.

You can configure it using

3 --provider <provider>
                                                --client-id <client_id>
                                                --client-secret <client_secret>