Getting Started
S3 Compatible Source Migration Guide

S3 Compatible Sources Migration Guide

Overview

Using the imgix Management API (opens in a new tab), this guide assists with migrating users from Web Folders to our newly supported S3 Compatible Sources. Sources can be created new or preexisting Web Folders can be converted into an S3 Compatible Source. The integrated S3-compatible Sources are listed here:

Once the Source has been migrated from a Web Folder to an S3 Compatible Source, public access to those affiliated buckets can be disabled.

Requirements

To create an S3-compatible Source, you will need the following from your S3-compatible storage provider:

  • Access Key
  • Secret Access Key
  • Bucket
  • Endpoint URL
  • Region

The region value is usually found in your S3-compatible Origin’s URL. Take for example this Linode bucket URL:

imgix-s3-compatible.us-east-1.linodeobjects.com

From that, you can extract the region value as us-east-1.

Every other required field can be found using your respective provider’s documentation:

DigitalOcean

Wasabi

Linode

Cloudflare R2

Using the Dashboard to Create a Source

We have several guides to help you create a Source in imgix, which you can read here:

If you have an existing Source that you wish to convert, you can do so by editing the Source's configuration and then changing the Source type.

Screenshot-Changing Source Type

Using the Management API

Creating/updating a Source using the Management API requires the following in addition to the S3-compatible provider requirements:

  • A valid imgix API Key (opens in a new tab) (with the Sources permission toggled)
    • If you do not have access to your account’s imgix API Key page, please contact your account administrator
  • Source ID (if you are converting a Web Folder source)
  • The storage_provider name. Valid values are:
    • DigitalOcean
    • Wasabi
    • Linode

Creating a New S3 Compatible Source

Using the Management API to create the Source:

 
POST https://api.imgix.com/api/v1/sources/$source_id
 
{
  "data": {
    "attributes": {
      "name": "$new_source_name",
      "deployment": {
        "type": "s3_compatible",
        "storage_provider": "$storage_provider",
        "access_key_id": "$access_key_id",
        "bucket_name": "$bucket_name",
        "secret_key": "$secret_key",
        "endpoint_url": "$endpoint_url",
        "region": "$region",
        "imgix_subdomains": [
          "$imgix_subdomain"
        ]
      }
    },
    "type": "sources"
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Migrating Existing Web Folder to S3 Compatible Source

Using the Management API to convert a Web Folder to an S3 Compatible Source:

PATCH  https://api.imgix.com/api/v1/sources/$source_id
 
{
  "data": {
  "attributes": {
    "name": "$sourceName",
    "deployment": {
        "type": "s3_compatible",
        "storage_provider": "$storage_provider",
        "access_key_id": "$access_key_id",
        "bucket_name": "$bucket_name",
        "secret_key": "$secret_key",
        "endpoint_url": "$endpoint_url",
        "region": "$region",
        "imgix_subdomains": [
            "$imgix_subdomain"
        ]
        }
  },
  "id": "$source_id",
  "type": "sources"
  },
  "jsonapi": {
  "version": "1.0"
  }
}

Example

Creating a new S3-compatible Source with DigitalOcean:

{
  "data": {
    "attributes": {
    "name": "DigitalOcean example Source",
    "deployment": {
      "type": "s3_compatible",
      "storage_provider": "DigitalOcean",
      "access_key_id": "$YOUR_DO_ACCESS_KEY",
      "bucket_name": "imgix-assets-digitalocean",
      "secret_key": "$YOUR_DO_SECRET_KEY",
      "endpoint_url": "sfo3.digitaloceanspaces.com",
      "region": "sfo3",
      "imgix_subdomains": [
      "imgix-digitalocean-example"
      ]
    }
    },
    "type": "sources"
  },
  "jsonapi": {
    "version": "1.0"
  }
}