Getting Started
Setting Up Asset Storage

Setting Up Asset Storage

File & Server Organization

  • Store your assets in a single location (unless using Web Proxy). A non-proxy imgix Source can only map to one location, but you can have multiple Sources if necessary (e.g. for testing and production).
  • Organizing your assets into folders within your root location (e.g. an Amazon S3 bucket or web folder) is fine for classifying further, and a folder at that level can be addressed specifically by a Source by adding it as the prefix. However, if you want to serve assets from more than one folder in the root location, you’ll need to set the Source to that location and add the folder name when building the asset URL. This will give you the best performance and flexibility.
  • Store only the highest-resolution version of each asset you want to serve. imgix is designed around the concept of a single high-resolution Origin Image that’s then used to generate as many derivatives (such as different sizes or crops) as you need.
  • Avoid special characters in folder and file names. They require encoding to resolve and if not handled carefully, can result in 404 errors for your assets. List of characters to avoid (opens in a new tab)
  • Fingerprint your assets to automatically manage updates and removals. imgix’s purging feature is quick and thorough, but it’s better to manage Origin Image updates by changing the filename everywhere it appears, along with updating the file itself. Our Fingerprinting Assets guide details how and why to fingerprint.

Cache-Control Headers

imgix offers flexibility in the way the service interacts with Cache-Control: max-age headers. The default Cache TTL behavior setting for all Source types except Google Cloud Storage is to respect a header if present (Respect origin), and apply a Default Cache TTL value of 1 year if not present. This is the easiest way to respect varying headers if you’ve set them, but have a reasonable setting otherwise that will use imgix’s caching architecture most effectively. Here are some common settings for other use cases—the Source setup docs have a complete explanation of imgix’s cache settings.

  • imgix defaults the Cache TTL Behavior mode in Advanced Source Settings for all new Google Cloud Storage Sources to Enforce minimum, which applies max-age=1yr, public to all files whether they have a header or not. This is to ensure that caching works on all files. See the Google Cloud Storage setup guide for more information.
  • If you need a different default expiration timeframe, keep Respect origin as the Cache TTL behavior, and change the Default Cache TTL value as desired.
  • If you want to ensure that all assets have the same max-age value without having to set them manually, set the Cache TTL behavior to Override origin and change the Override Cache TTL value as desired.

When Connecting to imgix

  • Choose your imgix subdomain name carefully. Once the name is attached to a Source, it can’t be transferred to another Source, even if the original Source is deleted (this applies to custom subdomains as well as standard ones). If you’re testing the service out, we recommend using a name you won’t need later for your production site—domain names will remain inextricably linked to their initial Source.
  • Don’t create multiple Sources to enable multiple asset requests. HTTP/2 support (opens in a new tab) means that sharding techniques that used to be a best practice for performance are now counterproductive.
  • If you store your assets in Amazon S3, create an IAM user with read-only permissions for your bucket. Use this set of credentials when setting up your Source for additional asset security (instructions are in the Amazon S3 setup guide).