# Configure your own buckets

{% hint style="danger" %}
**This documentation is for the CARTO Self-Hosted Legacy Version**. Use only if you've installed this specific version. Explore our latest documentation for updated features.
{% endhint %}

For every CARTO Self-Hosted installation, we need some configured buckets to store resources that will be used by the platform. These storage buckets are part of the required infrastructure for importing and exporting data, map thumbnails, customization assets (custom logos and markers) and other internal data.

You can create and use your own storage buckets in any of the following supported storage providers:

* [Google Cloud Storage](https://cloud.google.com/storage)
* [AWS S3](https://aws.amazon.com/s3/)
* [Azure Blob Storage](https://azure.microsoft.com/es-es/products/storage/blobs/)

## **Pre-requisites**

1. Create 2 buckets in your preferred Cloud provider:
   * **Import Bucket**
   * **Thumbnails Bucket**.

{% hint style="info" %}
There're no name constraints.

Map thumbnails storage objects (.png files) can be configured to be `public` (default) or `private`. In order to change this, set `WORKSPACE_THUMBNAILS_PUBLIC="false"`. Some features, such as branding and custom markers, won't work unless the bucket is public. However, there's a workaround to avoid making the whole bucket public, which requires allowing public objects, allowing ACLs (or non-uniform permissions) and disabling server-side encryption.
{% endhint %}

2. Create the **data export bucket**. This bucket has to be created in different storage providers depending on your data warehouse:
   * BigQuery: [Google Cloud Storage](https://cloud.google.com/storage)
   * Snowflake: [AWS S3](https://aws.amazon.com/s3/)
   * Redshift: [AWS S3](https://aws.amazon.com/s3/)
   * Amazon RDS: [AWS S3](https://aws.amazon.com/s3/)

For buckets created in AWS S3:

* ACLs should be allowed.
* If server-side encryption is enabled, the user must be granted with permissions over the KMS key following the [AWS documentation](https://repost.aws/knowledge-center/s3-bucket-access-default-encryption).

3. CORS configuration: Thumbnails and Import buckets require having the following CORS headers configured.
   * Allowed origins: `*`
   * Allowed methods: `GET`, `PUT`, `POST`
   * Allowed headers (common): `Content-Type`, `Content-MD5`, `Content-Disposition`, `Cache-Control`
     * GCS (extra): `x-goog-content-length-range`, `x-goog-meta-filename`
     * Azure (extra): `Access-Control-Request-Headers`, `X-MS-Blob-Type`
   * Max age: `3600`

{% hint style="info" %}
CORS is configured at bucket level in GCS and S3, and at storage account level in Azure.

How do I setup CORS configuration? Check the provider docs: [GCS](https://cloud.google.com/storage/docs/configuring-cors), [AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html), [Azure Blob Storage](https://docs.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services#enabling-cors-for-azure-storage).
{% endhint %}

4. Generate credentials with Read/Write permissions to access those buckets, our supported authentication methods are:
   * GCS: Service Account Key
   * AWS: Access Key ID and Secret Access Key
   * Azure Blob: Access Key

## Single VM deployments (Docker Compose)

### Import and Thumbnails buckets

{% tabs %}
{% tab title="Google Cloud Storage" %}
In order to use Google Cloud Storage custom buckets you need to:

1. Create a custom Service account.
2. Grant this service account with the following role (in addition to the buckets access): `roles/iam.serviceAccountTokenCreator`.
3. Set the following variables in your <mark style="color:orange;">customer.env</mark> file:

```
# Thumbnails bucket
WORKSPACE_THUMBNAILS_PROVIDER='gcp'
WORKSPACE_THUMBNAILS_PUBLIC=<true|false>
WORKSPACE_THUMBNAILS_BUCKET=<thumbnails_bucket_name>
WORKSPACE_THUMBNAILS_KEYFILENAME=/usr/src/certs/<gcp_key>.json
WORKSPACE_THUMBNAILS_PROJECTID=<gcp_project_id>

# Import bucket
IMPORT_PROVIDER='gcp'
IMPORT_BUCKET=<import_bucket_name>
IMPORT_KEYFILENAME=/usr/src/certs/<gcp_key>.json
IMPORT_PROJECTID=<gcp_project_id>
```

{% hint style="info" %}
The service account that is used to access the GCP buckets should be copied into the `certs` folder, which is located inside the CARTO installation folder.
{% endhint %}

> If `<BUCKET>_KEYFILENAME` is not defined env `GOOGLE_APPLICATION_CREDENTIALS` is used as default value. When the selfhosted service account is setup in a Compute Engine instance as the default service account, there's no need to set any of these, as the containers will inherit the instance default credentials.

> If `<BUCKET>_PROJECTID` is not defined env `GOOGLE_CLOUD_PROJECT` is used as default value.
> {% endtab %}

{% tab title="AWS S3" %}
In order to use AWS S3 custom buckets you need to:

1. Create an IAM user and generate a programmatic key ID and secret. If server-side encryption is enabled, the user must be granted with permissions over the KMS key used.
2. Grant this user with read/write access permissions over the buckets.
3. Set the following variables in your <mark style="color:orange;">customer.env</mark> file:

```
# Thumbnails bucket
WORKSPACE_THUMBNAILS_PROVIDER='s3'
WORKSPACE_THUMBNAILS_PUBLIC=<true|false>
WORKSPACE_THUMBNAILS_BUCKET=<thumbnails_bucket_name>
WORKSPACE_THUMBNAILS_ACCESSKEYID=<aws_access_key_id>
WORKSPACE_THUMBNAILS_SECRETACCESSKEY=<aws_access_key_secret>
WORKSPACE_THUMBNAILS_REGION=<aws_s3_region>

# Import bucket
IMPORT_PROVIDER='s3'
IMPORT_BUCKET=<import_bucket_name>
IMPORT_ACCESSKEYID=<aws_access_key_id>
IMPORT_SECRETACCESSKEY=<aws_access_key_secret>
IMPORT_REGION=<aws_s3_region>
```

{% endtab %}

{% tab title="Azure Blob Storage" %}
In order to use Azure Storage buckets you need to:

1. Create an storage account if you don't have one already.
2. Generate an Access Key, from the storage account's Security properties.
3. Set the following variables in your <mark style="color:orange;">customer.env</mark> file:

```
# Thumbnails bucket
WORKSPACE_THUMBNAILS_PROVIDER='azure-blob'
WORKSPACE_THUMBNAILS_PUBLIC=<true|false>
WORKSPACE_THUMBNAILS_BUCKET=<thumbnails_bucket_name>
WORKSPACE_THUMBNAILS_STORAGE_ACCOUNT=<storage_account_name>
WORKSPACE_THUMBNAILS_STORAGE_ACCESSKEY=<access_key>

# Import bucket
IMPORT_PROVIDER='azure-blob'
IMPORT_BUCKET=<import_bucket_name>
IMPORT_STORAGE_ACCOUNT=<storage_account_name>
IMPORT_STORAGE_ACCESSKEY=<access_key>
```

{% hint style="info" %}
The access key that is used to access the GCP buckets should be copied into the `certs` folder, which is located inside the CARTO installation folder.
{% endhint %}
{% endtab %}
{% endtabs %}

### Data export bucket

#### Configure data export bucket for BigQuery

To enable exporting data from BigQuery on CARTO Self-Hosted platform, we need a GCS bucket where we can store the exported data, and a service account with permissions to manage the bucket. These are the required steps:

1. Grant read/write permissions to the service account used by your CARTO Self-Hosted installation on the GCS export bucket created in the [pre-requisites](#pre-requisites).
2. Update the <mark style="color:orange;">customer.env</mark> file with the following values:

```
EXPORTS_GCS_BUCKET_NAME=<GCP_BUCKET_NAME>
EXPORTS_GCS_CREDENTIALS_KEY_FILENAME=/usr/src/certs/<GCP_KEY_NAME>.json
```

#### Configure data exports in Snowflake and Redshift

Snowflake and Redshift require an AWS S3 bucket to export data from CARTO platform. These are the needed steps for allowing exporting data from CARTO Self-Hosted in these providers:

1. Create an IAM user and generate a programmatic key ID and secret. If server-side encryption is enabled, the user must be granted with permissions over the KMS key used.

{% hint style="info" %}
If you've already configured the Import and Thumbnails buckets using AWS S3, you can use the same user you already created for these buckets.
{% endhint %}

2. Create an AWS IAM role with the following settings:

   1. Trusted entity type: `Custom trust policy`.
   2. Custom trust policy: Make sure to replace `<your_aws_user_arn>`.

   ```json
   {
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Principal": {
                 "AWS": "<your_aws_user_arn>"
             },
             "Action": [
                 "sts:AssumeRole",
                 "sts:TagSession"
             ]
         }
     ]
   }
   ```

   3. Add permissions: Create a new permissions' policy, replacing `<your_aws_s3_bucket_name>`.

   ```json
   {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "s3:ListBucket",
              "Resource": "arn:aws:s3:::<your_aws_s3_bucket_name>"
          },
          {
              "Effect": "Allow",
              "Action": "s3:*Object",
              "Resource": "arn:aws:s3:::<your_aws_s3_bucket_name>/*"
          }
      ]
   }
   ```
3. Add the following environment variables in your <mark style="color:orange;">customer.env</mark> file and apply the changes:

```
EXPORTS_S3_BUCKET_NAME=<BUCKET_NAME>
EXPORTS_S3_BUCKET_REGION=<REGION>
EXPORTS_S3_BUCKET_ROLE_ARN=<ROLE_ARN>
EXPORTS_S3_BUCKET_ACCESS_KEY_ID=<ACCESS_KEY_ID>
EXPORTS_S3_BUCKET_SECRET_ACCESS_KEY=<SECRET_ACCESS_KEY>
```

#### Configure data exports in Amazon RDS for PostgreSQL

The bucket to export data from Amazon RDS for PostgreSQL can be configured from the CARTO platform UI. Once your Self-Hosted installation is finished, you can check in the following documentation [how to configure your S3 bucket integration for Amazon RDS for PostgreSQL](https://docs.carto.com/carto-user-manual/settings/advanced-settings/configuring-s3-bucket-integration-for-rds-for-postgresql-exports-in-builder).