On-Premises Private

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/tools/embedded/bin

Note
All the operation tools must be executed with root user or full root privileges. Operation tools are executed through `cartoctl` via `cartoctl exec -- ` </div>
Warning
`cartoctl` can be executed from the Builder uncompressed tar ball folder, or from `/opt/carto/tools/bin/cartoctl`. In case of using the latter, make sure to use `--release-path` flag, pointing to a copy/backup of the uncompressed tar ball folder, otherwise some tools might fail. As a best practice, you can consistently use `--release-path /opt/carto/tools`.
### 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 carto-builder-ssl.sh tool: ``` bash cartoctl exec -- carto-builder-ssl.sh 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 carto-builder-create-org-with-admin.sh tool. For example: ``` bash cartoctl exec -- carto-builder-create-org-with-admin.sh --admin-user org-admin \ --password pass \ --email example@carto.com \ --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: ``` bash cartoctl exec -- carto-builder-create-org-with-admin.sh --admin-user org-admin \ --password pass \ --email example@carto.com \ --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
Note
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: ``` bash cartoctl exec carto-builder-feature-flags.sh 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 carto-builder-ldap.sh tool. The following is an example config for Windows Active Directory: ``` bash cartoctl exec -- carto-builder-ldap.sh --host 127.0.0.1 \ --port 389 \ --connection-user CN=Administrator,CN=Users,DC=carto,DC=com \ --connection-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 ``` #### 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 carto-builder-saml.sh 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: > > > ``` bash > cartoctl exec -- carto-builder-saml.sh --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: > > > ``` bash > cartoctl exec -- carto-builder-saml.sh --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., `http://192.168.20.2/saml2/idp/metadata.php`. 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:///user/orgname/saml/metadata` where `` is the value of `CARTO_DOMAIN` in your config file. - saml-idp-sso-target-url: SAML Identity Provider login URL, e.g., `http://192.168.20.2/simplesaml/saml2/idp/SSOService.php`. Required on manual configuration - saml-idp-slo-target-url: SAML Identity Provider logout URL, e.g., `http://192.168.20.2/simplesaml/saml2/idp/SingleLogoutService.php`. 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., `http://192.168.20.2/user/orgname/saml/finalize`. 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., `http://192.168.20.2/user/orgname/logout`. 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) ``` bash $ 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 `carto-builder-kerberos.sh` tool. The following example assumes a keytab file called `http.keytab` and the `DEVNET.LOCAL` realm.
multiple\_hosts Remember to execute `cartoctl exec -- carto-builder-kerberos.sh` in all the servers with nginx or builder roles.
Note
Before using the tool, remember to update your installation configuration `~/carto/.config.yml` to either set `CARTO_KERBEROS_ENABLED` and `CARTO_HTTP_HEADER_AUTHENTICATION` to `true` if enabling, or `false` when disabling. Preferably, config keys should be placed under builder role.
``` bash cartoctl exec -- carto-builder-kerberos.sh enable --keytab-file http.keytab --realm DEVNET.LOCAL ```
Warning
The `CARTO_USER` name set at installation time in the `~/carto/.config.yml` 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.
Note
Before using the tool, remember to update your installation configuration `~/carto/.config.yml` to either set `CARTO_ARCGIS_ENABLED` to `true` if enabling, or `false` when disabling. Preferably, config keys should be placed under builder role.
``` bash cartoctl exec -- carto-builder-arcgis.sh enable ``` Use the keyword `disable` to disable it ### BigQuery connector
Warning
BigQuery connector is supported on Red Hat and CentOS 8.x versions and it is not compatible with 7.x versions.
BigQuery connector can be enabled at any time and it requires a [Google Service Account Key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) with the suitable permissions to access to the Bigquery Service. ``` bash cartoctl exec -- carto-builder-bigquery.sh Usage: carto-builder-bigquery.sh enable/disable/add/del/list ... - Enable BigQuery connector specifiying default credentials: enable gcp_project credentials_email credentials_file Example: carto-builder-bigquery.sh enable mycompanybigquery carto-onprem@mycompanybigquery.iam.gserviceaccount.com /tmp/mycompanybigquery-cd0248fd47ae.json - Disable BigQuery connector: disable Example: carto-builder-bigquery.sh disable - Store extra credentials for using them with the Import API: add name credentials_file Example: carto-builder-bigquery.sh add ourstores /tmp/mycompanybigquery-483ac654b04f.json - Remove extra credentials: del name Example: carto-builder-bigquery.sh del ourstores - List extra credentials: list Example: carto-builder-bigquery.sh list ``` The connector can be used with a default Service Account Key, or using different additional keys stored in the instance. - When using Builder UI to import a table from BigQuery, the default key will be used. - When using the connector via Import API, a specific Service Account can be set just by adding the following parameters to the request: ``` json "connection": { "credentials_email": "CREDENTIALS_EMAIL", "credentials_file":" /data/config/bigquery/mycompanybigquery-483ac654b04f.json", "billing_project": "GCP_PROJECT" } ``` ### 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: ``` bash cartoctl exec -- carto-builder-enable-auth-api.sh ``` ### 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 `cartoctl exec -- carto-builder-configure-login-oauth-provider.sh`
Note
Before using the tool, remember to update your installation configuration using `~/carto/.config.yml` to update `CARTO_OAUTH_GOOGLE_CLIENT_ID`, `CARTO_OAUTH_GOOGLE_CLIENT_SECRET`, `CARTO_OAUTH_GITHUB_CLIENT_ID`, and `CARTO_OAUTH_GITHUB_CLIENT_SECRET` accordingly. Preferably, config keys should be placed under builder role.
``` bash cartoctl exec --carto-builder-configure-login-oauth-provider.sh --provider --client-id --client-secret ```