Documentation

Creating Sources

The first step in working with imgix is to create a Source, which connects imgix to your image storage. There are currently three types of Sources:

  • Amazon S3: Connects to an existing Amazon S3 bucket with its own credentials.
  • Web Folder: Proxies content from a given domain (or a subfolder on the domain).
  • Web Proxy: Can proxy any valid image URL.

The requirements for each Source type vary. Sources may also contain additional configuration options such a default parameters, default images, cache control headers, and cross-origin request information.


Creating an Amazon S3 Source

An Amazon S3 Source connects to an existing Amazon S3 bucket. imgix connects using the credentials you supply, so images are not required to be public.

Security

We strongly recommend creating an Amazon IAM account specifically for imgix to access your S3 bucket with. All Amazon credentials are stored using industry standard cryptographic best practices.

Easy & Secure

The “Amazon S3 Read Only Access” policy template for your IAM account provides the best mix of ease, protection, and imgix feature future-proofing.

  1. Go to your AWS IAM Dashboard
  2. Click Users on the left navigation
  3. Click Create New Users or select your user
  4. Click the Permissions tab and then the Attach Policy button
  5. You will be presented with a list of policy templates. Scroll down or search until you see “Amazon S3 Read Only Access” then click the Select button next to it.
  6. Click Apply Policy.

Advanced

imgix only needs a few read-only permissions to properly fetch images. To add an additional layer of security, use a limited-permissions IAM account that is only used for imgix and only for the bucket containing your images.

The specific S3 permissions imgix requires are:

  • ListBucket
  • GetBucketLocation
  • GetObject

Advanced Policy Example

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket/*",
        "arn:aws:s3:::your-bucket"
      ]
    }
  ]
}

Note: If you decide to manually build your policy, please double-check it with the Amazon IAM Policy Simulator.

When retrieving S3 objects from the us-east-1 region, imgix uses the s3-external-1.amazonaws.com hostname to retrieve images whenever possible to ensure read-after-write consistency, and will fall back to the default hostname of s3.amazonaws.com if necessary.

Screenshot-Amazon S3 source setup

  1. Log into your account.
  2. Go to the Sources section and click the New Source button.
  3. Name the Subdomain you’d like to use as the base URL for your images.
  4. Select Amazon S3 from the Source Type dropdown.
  5. Fill in the details for the Amazon S3 Source (see the security notice below about access/secret keys). The parameters are:
    • AWS Access Key: The access key of the credentials you want imgix to connect with.
    • AWS Secret Key: The secret key of the credentials you want imgix to connect with.
    • S3 Bucket: The name of the bucket containing the images you want imgix to connect to.
    • S3 Prefix: The folder prefix you want to resolve to. The prefix is prepended to the image path before resolving the image in S3. By default the image path is /.
  6. Click the Create Source button. Your Source will be staged for deployment and you will be directed to the Source Details page.



Creating a Web Folder Source

A Web Folder Source connects to your existing folder of images that are on a publicly addressable website, usually your website’s existing image folder.

Screenshot-Web folder source setup

  1. Log into your account.
  2. Go to the Sources section and click the New Source button.
  3. Name the Subdomain you’d like to use as the base URL for your images.
  4. Select Web Folder from the Source Type dropdown.
  5. Fill in the details for the Web Folder Source. The parameters are:
    • Base URL: The protocol, host, and path information to prepend to the path (such as http://www.yourcompany.com/images/).
  6. Click the Create Source button. Your Source will be staged for deployment and you will be directed to the Source Details page.

Creating a Web Proxy Source

A Web Proxy Source allows you to connect to any image that is addressable through a publicly-available URL. You provide the entire image URL of the master image in the path of the imgix request.

Screenshot-Web proxy source setup

  1. Log into your account.
  2. Go to the Sources section and click the New Source button.
  3. Name the Subdomain you’d like to use as the base URL for your images.
  4. Select Web Proxy from the Source Type dropdown. There are no parameters for the Web Proxy Source type.
  5. Click the Create Source button. Your Source will be staged for deployment and you will be directed to the Source Details page.

Security

All Web Proxy Sources require URL signing, unlike the other Source types where it is optional. For information on securely signing imgix URLs, please see the Securing Images guide.


Advanced Source Settings

The Source Details page shows you the current status of your Source and additional settings that can be configured. Within a few seconds of creating your Source, the Status field should change from Queued to Deployed. Once this happens, your Source is ready to use.

If you want to adjust the settings listed on this page, click on them, edit, and click Continue to Deploy to update your Source configuration. Most are self-explanatory (just hover over the (i) icons), but a few benefit from more detail.

Custom Domains

There is no specific setting for this, but if you want to use a custom subdomain as the base URL for your Source, you can add one. Both the standard subdomain and the custom will resolve to the same master image.

  1. Under Source Details, click Manage in the Domains field.
  2. Click Add Domain.
  3. Enter the custom subdomain you’d like to use and click outside of the field to save.
  4. Go to your DNS registrar and configure your DNS settings to ensure that the CNAME points to the Source’s imgix.net hostname.

Note: By default, you will only be able to use the custom subdomain with http. Using https requires an SSL certificate through our CDN partner and incurs additional fees—please contact Support to set this up. See the Securing Images guide for more detailed information.

Caching

You have the option to set Browser, Error, and Render TTLs for any Source. TTL stands for “Time to Live” and is measured in seconds. It determines how long the image will remain in cache. For more information on TTLs, see Wikipedia.

  • Browser: Sets the TTL on the browser’s cache.
  • Error: Sets the TTL on the CDN’s cache in the instance of an error, when the error code is greater than or equal to 400.
  • Render: Sets the TTL on the CDN’s cache.

In cases where an image does not contain a defined TTL, a minimum TTL will be applied. We will do our best to cache your derivative images for as long as you specify. However, the sheer number of possible image permutations that imgix enables you to create makes it impossible to perfectly cache all of your images forever.

At times, we may evict image derivatives from cache and re-render them as necessary. We will not bill you for derivative images that are evicted and re-rendered before the lesser of their intended cache timeout or 30 days.

We also recommend setting Cache-Control: max-age=31536000 headers on all images when you add them to your image storage. This will help reduce cache misses for files that imgix doesn’t process (like SVGs) and also prevent it from re-fetching images it does process from origin. If you need to update files that are already there, you can run a script like s3cmd (for Amazon S3) to set the header after uploading.

For more information on general caching strategy and how it interacts with imgix, see our Fingerprinting Images guide.


Next: Serving Images