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 IMGFORGE_PRESETS environment variable. Each preset maps a name to a slash-separated list of processing options.

Basic Format

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

Single Preset

export IMGFORGE_PRESETS="thumbnail=resize:fit:150:150/quality:80"

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

Multiple Presets

export IMGFORGE_PRESETS="thumbnail=resize:fit:150:150/quality:80,avatar=resize:fill:64:64/quality:85,banner=resize:fill:1200:300/quality:90"

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

Complex Presets

Presets can include any valid processing option:

export IMGFORGE_PRESETS="product_hero=resize:fit:1200:1200/quality:92/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 IMGFORGE_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 imgforge:

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:thumbnail/quality:95/<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://imgforge.example.com/${signature}/preset:thumbnail/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc

Presets-Only Mode

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

Configuration

export IMGFORGE_PRESETS="small=resize:fit:300:300,medium=resize:fit:600:600,large=resize:fit:1200:1200"
export IMGFORGE_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>/resize:fit:400:400/<encoded_url>         # raw option
✗ /<signature>/preset:small/quality:95/<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 IMGFORGE_PRESETS="default=quality:85,small=resize:fit:300:300"
export IMGFORGE_ONLY_PRESETS="true"

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

Preset Definition Best Practices

1. Use Descriptive Names

# Good
thumbnail=resize:fit:150:150
product_grid=resize:fit:300:300
hero_image=resize:fit:1920:1080

# Avoid
t=resize:fit:150:150
p1=resize:fit:300:300
x=resize:fit:1920:1080

Descriptive names make URL generation code self-documenting.

2. Include Common Options

# Complete preset
thumbnail=resize:fit:150:150/quality:80/format:webp/sharpen:0.8

# Minimal preset (relies on defaults)
thumbnail=resize:fit:150:150

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

3. Organize by Use Case

# E-commerce
export IMGFORGE_PRESETS="product_thumb=resize:fit:200:200/quality:85,product_main=resize:fit:800:800/quality:90,product_zoom=resize:fit:2000:2000/quality:92"

# Social media
export IMGFORGE_PRESETS="avatar_small=resize:fill:32:32/quality:85,avatar_medium=resize:fill:128:128/quality:88,og_image=resize:fit:1200:630/quality:90"

# Content management
export IMGFORGE_PRESETS="cms_thumb=resize:fit:300:200/quality:80,cms_medium=resize:fit:800:600/quality:85,cms_full=resize:fit:1920:1080/quality:90"

Group presets by domain or feature area.

4. Version Your Presets

# Include version in preset name if transformations may evolve
export IMGFORGE_PRESETS="thumbnail_v1=resize:fit:150:150/quality:80,thumbnail_v2=resize:fit:150:150/quality:85/format:webp"

This allows gradual migration when changing transformation logic.

Common Preset Patterns

Responsive Image Sets

Define presets for each breakpoint:

export IMGFORGE_PRESETS="\
mobile=resize:fit:400:400/quality:80/format:webp,\
tablet=resize:fit:800:800/quality:85/format:webp,\
desktop=resize:fit:1200:1200/quality:88/format:webp,\
retina=resize:fit:2400:2400/quality:90/format:webp"

Usage in HTML:

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

Avatar Sizes

export IMGFORGE_PRESETS="\
avatar_xs=resize:fill:32:32/gravity:center/quality:85,\
avatar_sm=resize:fill:64:64/gravity:center/quality:85,\
avatar_md=resize:fill:128:128/gravity:center/quality:88,\
avatar_lg=resize:fill:256:256/gravity:center/quality:90"

Format Variants

export IMGFORGE_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 IMGFORGE_PRESETS="\
fast=ra:linear/quality:75,\
balanced=ra:cubic/quality:85,\
premium=ra:lanczos3/quality:92/sharpen:1.0"

Watermarking

export IMGFORGE_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 IMGFORGE_PRESETS="default=quality:80,thumbnail=resize:fit:150:150/quality:90,sharp=sharpen:1.5"

URL:

/<signature>/preset:thumbnail/quality:95/preset:sharp/<encoded_url>

Expansion steps:

default=quality:80 → quality:80
preset:thumbnail → resize:fit:150:150/quality:90 (quality now 90)
quality:95 → (quality now 95, overrides preset)
preset:sharp → sharpen:1.5

Final options: resize:fit:150:150/quality:95/sharpen:1.5

Override Strategy

Later options always win:

# These all produce quality:95
/<sig>/preset:thumbnail/quality:95/<url>           # explicit override
/<sig>/quality:70/preset:thumbnail/<url>           # preset overrides earlier
/<sig>/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 IMGFORGE_PRESETS
Environment variable not loaded (server restart needed)

Fix:

# Verify preset is defined
echo $IMGFORGE_PRESETS

# Check imgforge startup logs
docker logs imgforge | 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 IMGFORGE_LOG_LEVEL="imgforge=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
/<sig>/pr:thumbnail/<url>

# Invalid - mixing preset with option
/<sig>/pr:thumbnail/quality:95/<url>

Preset Changes Not Applied

Symptom: Old preset definition still being used

Cause: Environment variable not reloaded

Fix:

# Update environment variable
export IMGFORGE_PRESETS="new_definition"

# Restart imgforge
systemctl restart imgforge
# or
docker restart imgforge

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
/<sig>/pr:thumbnail/<url>  → [cached]

# Update preset
export IMGFORGE_PRESETS="thumbnail=resize:fit:200:200/quality:90"  # was 150x150

# After: cache miss, new transformation
/<sig>/pr:thumbnail/<url>  → [cache miss, reprocess]

Cache invalidation strategy:

Version preset names when changing definitions:

thumbnail_v1=resize:fit:150:150
thumbnail_v2=resize:fit: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 IMGFORGE_PRESETS="thumbnail=resize:fit:150:150/quality:80"
export IMGFORGE_ONLY_PRESETS="true"

# Clients can only use defined presets
/<sig>/pr:thumbnail/<url>  ✓
/<sig>/resize:fit: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