Presets

Presets are named bundles of processing options that let you define reusable transformation recipes. Instead of repeating complex option chains in every URL, reference a preset by name. This document explains how to configure, use, and manage presets effectively.

Overview

Presets address common challenges in image transformation workflows:

Consistency – Apply identical transformations across your application
Maintainability – Update transformations globally by changing one definition
Simplicity – Shorter URLs that are easier to read and debug
Governance – Control which transformations are permitted
Security – Prevent arbitrary transformation requests in presets-only mode

Syntax:

preset:<name>
pr:<name>  # shorthand

Configuration

Define presets via the IMGFLUX_PRESETS environment variable. Each preset maps a name to a slash-separated list of processing options.

Basic Format

export IMGFLUX_PRESETS="name=option1:arg1/option2:arg2,name2=option3:arg3"

Single Preset

export IMGFLUX_PRESETS="thumbnail=trim:150:150q80"

This creates a preset called thumbnail that resizes images to 150×150 using the fit mode and outputs at 80% quality.

Multiple Presets

export IMGFLUX_PRESETS="thumbnail=trim:150:150q80,avatar=ex:64:64q85,banner=ex:1200:300q90"

Separate multiple presets with commas. Each preset name must be unique.

Complex Presets

Presets can include any valid processing option:

export IMGFLUX_PRESETS="product_hero=trim:1200:1200q92/sharpen:1.2/background:ffffff/watermark:0.7:south_east"

The Default Preset

A preset named default receives special treatment—it applies automatically to every request before URL-specific options or named presets.

Example

export IMGFLUX_PRESETS="default=quality:90/dpr:1/auto_rotate:true"

With this configuration, all images will:

Use 90% quality (unless overridden)
Apply 1.0 DPR scaling (unless overridden)
Honor EXIF orientation by default

URL options and named presets can still override these defaults.

Use Cases for Default Presets

Organization-wide quality standards – Enforce minimum quality across all images
Default DPR handling – Apply consistent device pixel ratio scaling
Format preferences – Set a default output format
Performance baselines – Apply sensible compression defaults
Security policies – Always apply certain safeguards

URL Usage

Basic Preset Reference

/<signature>/preset:thumbnail/<encoded_url>
/<signature>/pr:thumbnail/<encoded_url>  # shorthand

The pr: shorthand is equivalent to preset: and saves bytes in URLs.

The source URL segment that follows the preset can use either encoding style supported by imgFlux:

Base64 URL-safe – append an optional .<ext> suffix to force an output format
/<signature>/preset:thumbnail/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc.webp
Plain URL – start the segment with plain/ and percent-encode the URL, optionally adding @<ext>
/<signature>/preset:thumbnail/plain/https%3A%2F%2Fexample.com%2Fimage.jpg.webp

Choose whichever form matches your signing tooling; presets work the same either way.

Chaining Presets

Multiple presets can be combined:

/<signature>/preset:base/preset:quality_high/<encoded_url>

Later presets override earlier ones if they set the same parameter.

Mixing Presets and Options

Presets expand into options, so you can mix them freely:

/<signature>/preset:thumbnailq95/<encoded_url>

The explicit quality:95 overrides the quality setting from the thumbnail preset.

Signed URLs with Presets

Presets are part of the URL path and must be included in the signature:

# Path to sign
/preset:thumbnail/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc
 
# Generate signature for this path
signature=$(./sign_url.sh "/preset:thumbnail/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc")
 
# Full URL
https://imgFlux.example.com/${signature}/preset:thumbnail/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc

Presets-Only Mode

Enable strict governance by setting IMGFLUX_ONLY_PRESETS=true. In this mode, imgFlux rejects URLs that contain non-preset processing options.

Configuration

export IMGFLUX_PRESETS="small=trim:300:300,medium=trim:600:600,large=trim:1200:1200"
export IMGFLUX_ONLY_PRESETS="true"

Allowed Requests

✓ /<signature>/preset:small/<encoded_url>
✓ /<signature>/pr:medium/<encoded_url>
✓ /<signature>/preset:small/preset:large/<encoded_url>  # chaining OK

Rejected Requests

✗ /<signature>/trim:400:400/<encoded_url>         # raw option
✗ /<signature>/preset:smallq95/<encoded_url>    # mixed with option
✗ /<signature>/blur:5/<encoded_url>                     # non-preset option

All rejected requests return 400 Bad Request with an error message.

Use Cases for Presets-Only Mode

Multi-tenant platforms – Prevent users from creating arbitrary transformations
Cost control – Limit processing to pre-approved operations
Security hardening – Reduce attack surface by disallowing custom options
Compliance – Enforce transformation policies for regulated content
Client SDKs – Simplify integration by providing fixed preset names

Exception: Default Preset

If a default preset exists, requests with no processing options at all will still succeed in presets-only mode, because the default preset is implicitly applied:

export IMGFLUX_PRESETS="default=quality:85,small=trim:300:300"
export IMGFLUX_ONLY_PRESETS="true"

✓ /<signature>/<encoded_url>  # Allowed: default preset applies

Preset Definition Best Practices

1. Use Descriptive Names

# Good
thumbnail=trim:150:150
product_grid=trim:300:300
hero_image=trim:1920:1080
 
# Avoid
t=trim:150:150
p1=trim:300:300
x=trim:1920:1080

Descriptive names make URL generation code self-documenting.

2. Include Common Options

# Complete preset
thumbnail=trim:150:150q80/format:webp/sharpen:0.8
 
# Minimal preset (relies on defaults)
thumbnail=trim:150:150

Including quality, format, and sharpening in presets reduces surprises.

3. Organize by Use Case

# E-commerce
export IMGFLUX_PRESETS="product_thumb=trim:200:200q85,product_main=trim:800:800q90,product_zoom=trim:2000:2000q92"
 
# Social media
export IMGFLUX_PRESETS="avatar_small=ex:32:32q85,avatar_medium=ex:128:128q88,og_image=trim:1200:630q90"
 
# Content management
export IMGFLUX_PRESETS="cms_thumb=trim:300:200q80,cms_medium=trim:800x600q85,cms_full=trim:1920:1080q90"

Group presets by domain or feature area.

4. Version Your Presets

# Include version in preset name if transformations may evolve
export IMGFLUX_PRESETS="thumbnail_v1=trim:150:150q80,thumbnail_v2=trim:150:150q85/format:webp"

This allows gradual migration when changing transformation logic.

Common Preset Patterns

Responsive Image Sets

Define presets for each breakpoint:

export IMGFLUX_PRESETS="\
mobile=trim:400:400q80/format:webp,\
tablet=trim:800:800q85/format:webp,\
desktop=trim:1200:1200q88/format:webp,\
retina=trim:2400:2400q90/format:webp"

Usage in HTML:

<picture>
  <source srcset="/<teamName>/pr:mobile/<url>" media="(max-width: 640px)">
  <source srcset="/<teamName>/pr:tablet/<url>" media="(max-width: 1024px)">
  <source srcset="/<teamName>/pr:desktop/<url>" media="(max-width: 1920px)">
  <img src="/<teamName>/pr:retina/<url>" alt="...">
</picture>

Avatar Sizes

export IMGFLUX_PRESETS="\
avatar_xs=ex:32:32/gravity:centerq85,\
avatar_sm=ex:64:64/gravity:centerq85,\
avatar_md=ex:128:128/gravity:centerq88,\
avatar_lg=ex:256:256/gravity:centerq90"

Format Variants

export IMGFLUX_PRESETS="\
webp_hq=quality:92/format:webp,\
jpeg_hq=quality:90/format:jpeg,\
png_transparent=format:png,\
avif_modern=quality:85/format:avif"

Combine with other presets:

/<signature>/preset:thumbnail/preset:webp_hq/<encoded_url>

Performance Tiers

export IMGFLUX_PRESETS="\
fast=ra:linearq75,\
balanced=ra:cubicq85,\
premium=ra:lanczos3q92/sharpen:1.0"

Watermarking

export IMGFLUX_PRESETS="\
watermark_light=watermark:0.5:south_east,\
watermark_strong=watermark:0.8:south_east,\
watermark_centered=watermark:0.7:center"

Preset Expansion Order

Understanding expansion order helps predict the final result when combining multiple presets and options.

Expansion sequence:

Default preset (if defined) expands first
URL options/presets expand left-to-right
Later values override earlier ones for the same parameter

Example

Configuration:

export IMGFLUX_PRESETS="default=quality:80,thumbnail=trim:150:150q90,sharp=sharpen:1.5"

URL:

/<signature>/preset:thumbnailq95/preset:sharp/<encoded_url>

Expansion steps:

default=quality:80 → quality:80
preset:thumbnail → trim:150:150q90 (quality now 90)
quality:95 → (quality now 95, overrides preset)
preset:sharp → sharpen:1.5

Final options: trim:150:150q95/sharpen:1.5

Override Strategy

Later options always win:

# These all produce quality:95
/<teamName>/preset:thumbnailq95/<url>           # explicit override
/<teamName>q70/preset:thumbnail/<url>           # preset overrides earlier
/<teamName>/preset:low_quality/preset:high_quality/<url> # second preset wins

This makes it safe to set defaults and override selectively.

Troubleshooting

Preset Not Found Error

Symptom: 400 Bad Request with message "unknown preset: xyz"

Causes:

Preset name misspelled in URL
Preset not defined in IMGFLUX_PRESETS
Environment variable not loaded (server restart needed)

Fix:

# Verify preset is defined
echo $IMGFLUX_PRESETS
 
# Check imgFlux startup logs
docker logs imgFlux | grep -i preset

Unexpected Transformation Results

Symptom: Image doesn't match expected dimensions/quality

Causes:

Option override you didn't expect
Default preset applying unintended options
Multiple presets with conflicting settings

Debug:

# Enable debug logging
export IMGFLUX_LOG_LEVEL="imgFlux=debug"
 
# Check logs for "Applying default preset" or "Expanding preset"
# This shows exact expansion sequence

Presets-Only Mode Rejecting Valid Presets

Symptom: 400 Bad Request even with preset:name in URL

Causes:

Extra processing options mixed with preset
Typo: preset_name instead of preset:name
Space or special character in preset name

Fix:

# Valid in presets-only mode
/<teamName>/pr:thumbnail/<url>
 
# Invalid - mixing preset with option
/<teamName>/pr:thumbnailq95/<url>

Preset Changes Not Applied

Symptom: Old preset definition still being used

Cause: Environment variable not reloaded

Fix:

# Update environment variable
export IMGFLUX_PRESETS="new_definition"
 
# Restart imgFlux
systemctl restart imgFlux
# or
docker restart imgFlux

Caching with Presets

Cached images are stored by full URL path (including expanded preset). Changing a preset definition invalidates the cache for all URLs using that preset:

# Before: cached with old definition
/<teamName>/pr:thumbnail/<url>  → [cached]
 
# Update preset
export IMGFLUX_PRESETS="thumbnail=trim:200:200q90"  # was 150x150
 
# After: cache miss, new transformation
/<teamName>/pr:thumbnail/<url>  → [cache miss, reprocess]

Cache invalidation strategy:

Version preset names when changing definitions:
thumbnail_v1=trim:150:150 thumbnail_v2=trim:200:200
Drain cache gradually by updating application code to use new preset name
Purge cache explicitly if immediate update is required

Security Considerations

Preset Definition Protection

Presets are defined server-side and cannot be modified by clients. This makes them safer than allowing arbitrary options:

# Safe: preset controls transformations
export IMGFLUX_PRESETS="thumbnail=trim:150:150q80"
export IMGFLUX_ONLY_PRESETS="true"
 
# Clients can only use defined presets
/<teamName>/pr:thumbnail/<url>  ✓
/<teamName>/trim:9999:9999/<url>  ✗ rejected

Signature Coverage

Preset names are part of the URL path and must be included in the HMAC signature. This prevents:

Preset name tampering
Substituting one preset for another
Adding presets to unsigned URLs

Presets

On this page