Search Documentation

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. Go to the Sources page in the imgix dashboard and click the New Source button.

  2. Select Web Folder from the Source Type dropdown. Screenshot-Web folder source setup

  3. 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/).
  4. Name the Subdomain you’d like to use as the base URL for your images.

    Note: The subdomain name you choose is unique to your Source and can’t be re-used. If you’re setting up a Source with a lot of customization (particularly a Custom Domain), choose the name you plan to use going forward.

  5. Click the Save button. Your Source will be queued for deployment and you will be directed to the Source Details page.

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 domain 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. You can add up to 100 imgix subdomains and custom domains.

  1. On the Source Details page, click Edit.
  2. Under “Domains”, click Custom Domain (on mobile devices, click Add Domain first). 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 and ch cannot be set as default parameters, due to the way they interact 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

Your cache settings determine how long the derivative images generated by imgix will live in the end user’s browser cache. We generally recommend setting the TTL (or “time-to-live”) value to at least 1 year since the Master images are unlikely to change in that time. This way, the images are more likely to be served from the user’s local cache instead of being regenerated from the Master or served from intermediate caches in the imgix system, giving users faster page loads and lowering your bandwidth costs.

For more information on TTLs, see Wikipedia.

The Cache TTL Behavior dropdown determines how imgix interacts with any Cache-Control: max-age headers present on your Master images (in Origin). It has three options with corresponding TTL values:

  • Respect origin: Respects the Cache-Control: max-age header if present, applies one with the Default Cache TTL value if not present.
  • Override origin: Overrides the Cache-Control: max-age header with the Override Cache TTL value if a header is present, applies one with that value if not present.
  • Enforce minimum: Applies a Cache-Control: max-age header with the Minimum Cache TTL value if a header is not present, overrides the existing header if its value is lower than the Minimum Cache TTL value.

In addition to setting the default behavior and value for image caching, you can also set a Cache-Control: max-age header for the default error image (if you have set one). This value should be short so that the error image doesn’t continue to display after the error has resolved.

Here’s how to set your TTL values.

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

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.

Note: If you change your Cache TTL settings after your Source has been deployed, any images that were requested under the old settings will need to be purged for the new settings to take effect.

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


Next: Serving Images