ImagePipe documentation

ImagePipe resizes, crops, and converts images, either on request over HTTP or in Elixir code. Start with the page for what you want to do:

I want to…	Start with
Request images from an external ImagePipe server	Requesting images
Run `image_pipe_server`	Getting started with the server, then deploying and configuring it
Serve images from my Phoenix or Plug app	Getting started with Phoenix
Process images in Elixir code (uploads, jobs)	Processing images in Elixir, then the Elixir API
Generate signed URLs for a separate server	Building URLs for the server, then shared URL settings and fetching images from the server
Extend ImagePipe with custom sources, detectors, or telemetry handlers	Custom sources, custom detectors, and telemetry handlers

Getting started

First steps for each way of running ImagePipe.

Installation: the Hex dependency and supported image formats.
Getting started with the server: run image_pipe_server in Docker and request your first images.
Getting started with Phoenix: serve resized images from a new Phoenix app.
Processing images in Elixir: resize, crop, and convert a photo from iex.
Elixir API: the Elixir entry points and their guides.
Building URLs for the server: generate signed URLs for a separate image_pipe_server.

How image URLs work, and what each processing option does to the picture.

Requesting images: URL structure, option values, presets, and signed URLs.
Processing options: the complete option index and common recipes.
Resize and layout: dimensions, fit, DPR, zoom, canvas, padding, and background.
Orientation and cropping: rotation, flip, trim, regions, anchors, and detection.
Effects: blur, sharpen, pixelate, color adjustments, and overlays.
Watermarks: image watermarks with opacity, scale, placement, and tiling.
Output and encoding: formats, quality, size budgets, encoders, placeholders, and info.
Request controls: downloads, page selection, cache busting, expiry, and debugging.

Guides for deploying, connecting sources, caching, securing, and monitoring.

Deploying image_pipe_server: Docker, Kubernetes, health checks, and capacity.
Limiting work per request: limits on originals, timeouts, slow clients, and memory.
Image sources: what a source is, routing, and the available sources.
Serving images from local files: read originals from a directory.
Serving images from an HTTP origin: download originals from a web server.
Serving images from S3: read originals from private S3-compatible buckets.
Caching processed images: store processed images on disk and share them between replicas.
Serving images through a CDN: cache headers, source lifetimes, and CDN settings.
Signing URLs and rotating keys: require signed URLs and replace keys safely.
Defining presets: named sets of URL options.
Enabling face and object detection: install the detector and load its models.
Limiting concurrent processing: how many images are processed at once, queues, and deadlines.
Monitoring with telemetry: logging, metrics handlers, and request IDs.
Exporting traces to Jaeger: send traces to a local Jaeger.
Serving and processing in one app: serve images and process them in code with one configuration.
Fetching images from the server: use processed images inside your application.

Why ImagePipe behaves the way it does.

Processing order and groups: the fixed stage order, and groups that run options in a different order.
Caching and freshness: how long originals and processed images stay valid.
Failures during streaming: what happens when encoding fails after headers are sent.
Signing and source concealment: what a signature covers, expiry, and hidden source paths.
Presets: request defaults, precedence, and pipeline presets.
Content-aware cropping: how attention and detection choose what a crop keeps.
Source network policy: what HTTP sources may connect to.
Request tracing: how traces are built, inbound trace context, and sampling.

Plug in your own stores, detectors, and preset storage.

Settings, headers, events, and rules to look up.

Elixir configuration: where each Elixir setting goes, and which wins when they overlap.
Configuring image_pipe_server: the server's TOML and environment variables.
Shared URL settings: settings the URL builder and the server must agree on.
Cache storage: what the caches store, cache key inputs, and bounded mode.
HTTP cache headers: Cache-Control, ETag, Vary, and 304 responses.
Error responses: which status each failure returns.
Telemetry event reference: event names, measurements, metadata, and outcomes.
Debug response headers: inspect processing and cache decisions.

About the project itself.