CARTO Self Hosted [Docker]

CARTO Self Hosted [Docker]

This repository contains the necessary files for deploying a CARTO Self Hosted installation in your own cloud infrastructure using docker-compose.

To be able to run CARTO Self Hosted you need to have a license. Contact CARTO to get one.

If you are looking for another installation method, CARTO Self Hosted is provided in two flavors:

Installation

⚠️ CARTO provides an out-of-the-box installation that is not production ready. In order to make your CARTO installation production ready take a look at the customization section.

Prerequisites

You will need a Linux machine with at least:

Ubuntu 18.04 or above
60 GB disk
2 CPUs (x86)
8 GB memory
Docker version 20.10 or above
Docker compose version 1.29 or above
A TLS certificate for the domain/subdomain (if not provided a self-signed one will be generated)
Configuration and license files received from CARTO
Internet HTTP/HTTPS access from the machine to the whitelisted domains list

Note that you should additionally allow access to any datawarehouse endpoint configured.

Deployment Customizations

Please, read the available customization options.

Installation Steps

Log into the machine where you are going to deploy CARTO.

Clone this repository:

git clone https://github.com/CartoDB/carto-selfhosted.git
cd carto-selfhosted

After contacting CARTO, you should have received two files, copy them in the current directory (carto-selfhosted):
- customer.env
- key.json
Configure your CARTO Self Hosted domain by updating the env var SELFHOSTED_DOMAIN value, which defaults to carto3-onprem.lan. In order to access your CARTO Self Hosted you should modify your /etc/hosts file to point localhost to this domain:
```
sudo vi /etc/hosts
```
```
# Carto Self Hosted
127.0.0.1 carto3-onprem.lan
```
Configure your deployment. Please, read the available customization options.
Checkout to the latest stable release:
```
git checkout tags/2022.12.14
```
Run the install.sh script to generate the .env file out of the customer.env file:
```
bash install.sh
```
Bring up the environment:
```
docker-compose up -d
```
Open a browser and go to https://carto3-onprem.lan (or the custom domain configured).

Post-installation Checks

In order to verify CARTO Self Hosted was correctly installed and it's functional, we recommend performing the following checks:

Check all the containers are up and running:
```
docker-compose ps
```
All containers should be in state Up, except for workspace-migrations which state should be Exit 0, meaning the database migrations finished correctly.
Sign in to your Self Hosted, create a user and a new organization.
Go to the Connections page, in the left-hand menu, create a new connection to one of the available providers.
Go to the Data Explorer page, click on the Upload button right next to the Connections panel. Import a dataset from a local file.
Go back to the Maps page, and create a new map.
In this new map, add a new layer from a table using the connection created in step 3.
Create a new layer from a SQL Query to the same table. You can use a simple query like:
```
SELECT * FROM <dataset_name.table_name> LIMIT 100;
```
Create a new layer from the dataset imported in step 4.
Make the map public, copy the sharing URL and open it in a new incognito window.
Go back to the Maps page, and verify your map appears there and the map thumbnail represents the latest changes you made to the map.

Update

To update you CARTO Self Hosted to the newest version you will need run the following commands:

Go to the CARTO installation directory:
```
cd carto-selfhosted
```
Pull last changes from the origin repo:
```
git pull
```
Save a backup copy of your current customer.env:
```
mv customer.env customer.env.bak
```
Download the latest customer package (containing customer.env and key.json files) using the tool described here. Then unzip the file.
Copy the new customer.env file in the installation directory:
```
cp /new_file_location/customer.env .
```
Open side by side customer.env and customer.env.bak and apply the customizations from customer.env.bak in the new customer.env
Generate the .env file
```
bash install.sh
```
Recreate the containers
```
docker-compose up -d
```

Uninstall

You can just stop the Self Hosted services (including removing any volumes from the system) and delete the carto-selfhosted directory.

⚠️ In case you are running a local Postgres database (which is not recommended for Production environments), take into account that removing the docker volumes will delete the database information and your CARTO Self Hosted users information with it.

docker-compose down -V

Migrate to Kubernetes

To migrate your CARTO Self Hosted from Docker Compose installation to Kubernetes/Helm you need to follow these steps:

⚠️ Migration incurs in downtime. To minimize it, reduce the DNS TTL before starting the process

Preconditions

You have a running Self Hosted deployed with Docker Compose i.e using a Google Compute engine instance.
You have configured external databases (Redis and PostgreSQL).
You have a K8s cluster to deploy the new self hosted and credentials to deploy.
You have received a new customer package from CARTO (with files for Kubernetes and for Docker). If you do not have them, please contact Support.

Steps

Update Docker installation to the latest release with the customer package received.
Allow network connectivity from k8s nodes to your pre-existing databases. i.e (Cloud SQL connection notes).

Create a customizations.yaml following this instructions. Keep the same external database connection settings you are using in CARTO for Docker. Postgres and Redis.

⚠️ NOTE: Do not trust the default values and fill all variables related to database connections, example:

externalPostgresql:
  host: "<yourPostgresqlHost>"
  adminUser: postgres
  adminPassword: <adminPassword>
  password: <userPassword>
  database: workspace
  user: workspace_admin
  sslEnabled: true
internalPostgresql:
  enabled: false

internalRedis:
  # Disable the internal Redis
  enabled: false
externalRedis:
  host: "yourRedisHost"
  port: "6379"
  password: <AUTH string>"
  tlsEnabled: false

Read also the instructions on how to expose the Kubernetes installation to outside the cluster.

Create a customizations.yaml following these instructions. Keep the same external database connection settings you are using in CARTO for Docker. Postgres and Redis.
Shut down you CARTO for Docker installation: docker-compose down.

Once you execute this, the service is down.
Deploy to your cluster. Follow the installation steps.
Check pods are running and stable with kubectl get pods <-n your_namespace>.
Change DNS records to point to the new service (helm install will point how to get the IP or DNS), it will take some time to propagate.
Test your CARTO Self Hosted for Kubernetes installation. Service is restored.

If for whatever reason the installation did not go as planned. You can bring back the docker installation and point back your DNS to it.

scleveland / carto-selfhosted

Table of Contents