Elixir configuration

Copy Markdown View Source

An ImagePipe configuration holds the settings that apply to every image you serve or process: sources, caches, limits, output defaults, presets, and URL settings such as signing keys. You build it with ImagePipe.config/1, which lists every option with its default.

config =
  ImagePipe.config(
    base_url: "/images",
    keys: [signing_key],
    sources: [
      media: [
        adapter: ImagePipe.Source.File,
        match: :path,
        options: [root: "/srv/images", root_id: "media"]
      ]
    ],
    presets: %{"card" => "w=400/h=300/fit=cover"},
    max_input_pixels: 40_000_000,
    quality: 82
  )

A mount, an instance, or a call to ImagePipe.run/4 takes this configuration. Invalid options raise ArgumentError when you build it.

Where settings belong

SettingExamplesSet with
ConfigurationSources, caches, limits, output defaults, presets, and URL settings (signing keys, source encryption keys, base URL)ImagePipe.config/1
A sourceRoot directory, allowed hosts, timeouts, S3 credentialsThe source's options:, listed in its adapter's docs, such as ImagePipe.Source.HTTP
A mountCORS, HTTP cache headersImagePipe.Plug options on the forward
An instanceIts name, and which detection models load at startup (detector_warmup:)ImagePipe.child_spec/1
A requestSize, crop, effects, format, qualityURL options, or ImagePipe.URL.group/2 and ImagePipe.URL.output/2
A direct callThe Accept value, header and cookie values for cached copiesaccept: and vary_values: on ImagePipe.run/4

A mount checks request URLs against the configuration's URL settings. To build URLs in the same app, get those settings with ImagePipe.url_config/1. A separate app needs the same keys (see shared URL settings).

An instance has one set of URL settings. To serve URLs with different signing keys, such as signed and unsigned URLs, start an instance for each. Instances that use caches each need their own cache roots: two instances can't share a cache root.

Which setting wins

When the same setting is given in more than one place:

  • Options passed to an inline mount next to config: replace that configuration's options. A mount of an instance accepts only mount options.
  • Options passed to an instance next to config: replace that configuration's options.
  • Options passed to ImagePipe.run/4 or ImagePipe.write/5 replace the configuration's options for that call.
  • A request's own options win over the configuration's defaults. A URL with q=90 uses quality 90 whatever quality says.
  • Presets apply in a fixed order: request_defaults first, then the named presets in the order the URL lists them, then the request's own options. See presets.

Encoder defaults

:jpeg_options, :png_options, :webp_options, and :avif_options set encoder defaults. They take the same keyword lists as the options of the same name in ImagePipe.URL.output/2:

config =
  ImagePipe.config(
    jpeg_options: [interlace: true],
    webp_options: [effort: 5]
  )

builder =
  ImagePipe.URL.new()
  |> ImagePipe.URL.output(format: :jpeg, jpeg_options: [interlace: false])

A request's settings replace the configuration's field by field, so this builder encodes a baseline JPEG and keeps any other JPEG defaults. The fields are listed in encoder options under their URL names. Hyphens become underscores, and progressive and subsample have different builder names, listed in URL option names.

WebP encodes at effort: 4 and AVIF at effort: 3 unless :webp_options or :avif_options set another :effort. AVIF also encodes without chroma subsampling (subsample_mode: :off) unless :avif_options sets another :subsample_mode. See WebP options and AVIF options for the time and size tradeoff.

Limits and cached images

The limits, such as max_input_pixels and max_result_width, set the largest images ImagePipe processes. They don't apply to images already in the cache. After you lower a limit, cached images that exceed it are still served from the cache.