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.

Note: When naming your Source subdomain, only a single level is allowed. For example, images.imgix.net will be allowed, but my.images.imgix.net will not.

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.

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.

  1. Log into your account.
  2. Go to the Sources section and click the New Source button.
  3. Select Amazon S3 from the Source Type dropdown. Screenshot-Amazon S3 source setup
  4. 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 /.
  5. Name the Subdomain you’d like to use as the base URL for your images.
  6. Click the Save button. Your Source will be staged for deployment. Screenshot-Amazon S3 source setup


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.

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.

  1. Log into your account.
  2. Go to the Sources section and click the New Source button.
  3. Select Web Folder from the Source Type dropdown. Screenshot-Web folder source setup
  4. 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/).
  5. Name the Subdomain you’d like to use as the base URL for your images.
  6. Click the Save 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.

  1. Log into your account.
  2. Go to the Sources section and click the New Source button.
  3. Select Web Proxy from the Source Type dropdown. There are no parameters for the Web Proxy Source type. Screenshot-Web proxy source setup
  4. Name the Subdomain you’d like to use as the base URL for your images.
  5. Click the Save 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 (note that the Secure URLs box is checked and uneditable in the screen shot above). 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 the Edit button, edit the fields you want to change, and click Review and Deploy to update your Source configuration. Most fields are self-explanatory, but you can hover over the (?) icons to get more detail.

Custom Domains

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. On the Source Details page, click Edit.
  2. Under “Domains”, click Custom Domain. Screenshot-Custom domain source setup
  3. Enter the custom subdomain you’d like to use and click the Review & Deploy button to redeploy your Source with the new custom domain.
  4. Go to your DNS registrar and configure your DNS settings to ensure that the CNAME points to the new *.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.

Default and Error Images

Your Source comes equipped with some basic error-proofing, allowing you to set an image that appears in place of a missing image or one that has an error. This way, even if there is a problem with the image it will not appear blank. For either type of image, you also have the option to apply the parameters from the original image request.

To add either a default image or an error image:

  1. On the Source Details page, click Edit.
  2. Under “Image Defaults”, click in the appropriate field and enter the URL for your image. Screenshot-Default image setup
  3. If you want to apply the defaults from the original image request, click the check box under the image field.
  4. Click the Review & Deploy button to redeploy your Source with the new settings.

Default Parameters

If you have a baseline level of image optimization you’d like to apply to all of your images, you can specify default parameters at the Source level.

Note: auto=format cannot be set as a Source’s default parameter, due to the way it interacts with our caching infrastructure.

  1. On the Source Details page, click Edit.
  2. Under “Image Defaults”, choose a parameter from the dropdown menu and provide the value. Add as many parameter/value pairs as you’d like to set your defaults. Screenshot-Default parameter setup
  3. Click the Review & Deploy button to redeploy your Source with the new settings.

For more information about default parameters, how to override them, and recommended uses, check out this blog post.

Cache Settings

You have the option to set Browser and Error 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.

Here’s how to set them.

  1. On the Source Details page, click Edit.
  2. Under “Cache Settings”, enter a value for the TTL you want to change, and choose the time units from the dropdown menu. Screenshot-Custom domain source setup
  3. Click the Review & Deploy button to redeploy your Source with the new cache settings.

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