Skip to content

configuration.mdx

Latest commit

 

History

History
105 lines (81 loc) · 6.56 KB

configuration.mdx

File metadata and controls

105 lines (81 loc) · 6.56 KB
Raw

Configuration

imgx reads all configuration from environment variables prefixed with IMGX_. Every variable is optional and has a sensible default. The legacy ZIMGX_ prefix (from the prior Zig implementation) is still read as a fallback for one release; prefer IMGX_ for all new configuration.

Server

Variable Type Default Description
IMGX_SERVER_PORT u16 8080 TCP port to listen on
IMGX_SERVER_HOST string 0.0.0.0 IP address to bind to. Set to 127.0.0.1 to restrict to localhost.
IMGX_SERVER_REQUEST_TIMEOUT_MS u32 30000 Maximum time (ms) to wait for a complete request
IMGX_SERVER_MAX_REQUEST_SIZE usize 52428800 (50 MiB) Maximum request/response body size in bytes

Origin

Variable Type Default Description
IMGX_ORIGIN_TYPE string http http fetches from IMGX_ORIGIN_BASE_URL. r2 fetches from an R2 bucket.
IMGX_ORIGIN_BASE_URL string http://localhost:9000 Base URL for the HTTP origin. The image path is appended to this value.
IMGX_ORIGIN_TIMEOUT_MS u32 10000 Timeout (ms) for origin fetch requests
IMGX_ORIGIN_MAX_RETRIES u8 2 Retry attempts for failed origin fetches
IMGX_ORIGIN_PATH_PREFIX string "" Path prefix to strip from image paths before fetching from origin. When set, requests for /<prefix>/<key> resolve to origin key <key>. Useful for Cloudflare Images migration where URLs include the account ID.
IMGX_ALLOW_REMOTE_SOURCES bool false Allow the source-image segment of a request to be an absolute http:///https:// URL (Cloudflare parity: /image/<OPTIONS>/<SOURCE-IMAGE> where <SOURCE-IMAGE> is a full URL), fetched directly instead of from IMGX_ORIGIN_BASE_URL. Security warning: enabling this means imgx will fetch whatever URL a client's request names. A dedicated SSRF-safe fetcher enforces a scheme allowlist (http/https only), rejects addresses that resolve (or are given literally) as private/loopback/link-local/CGNAT, caps and re-validates redirects, and applies the same size/timeout limits as the configured origin — but these guards mitigate, not eliminate, risk against internal services. Only enable this if you understand and accept that risk, ideally alongside network-level isolation (e.g. running imgx without access to internal-only services/metadata endpoints). See docs/INVARIANTS.md INV-14 and docs/CLOUDFLARE_PARITY.md gap 2.
IMGX_ALLOW_DRAW_OVERLAYS bool false Allow draw[].url overlay images (Cloudflare parity: draw.<N>.url=...) to be fetched from an arbitrary http:///https:// URL. Independent of IMGX_ALLOW_REMOTE_SOURCES — enable one without the other if you only want overlays, or only want remote main sources. Reuses the exact same SSRF-safe fetcher and guards; the same security warning above applies. See docs/CLOUDFLARE_PARITY.md gap 11.

R2/S3

Required when IMGX_ORIGIN_TYPE=r2. All fields must be non-empty.

Variable Type Default Description
IMGX_R2_ENDPOINT string "" R2/S3-compatible endpoint URL
IMGX_R2_ACCESS_KEY_ID string "" Access key ID
IMGX_R2_SECRET_ACCESS_KEY string "" Secret access key
IMGX_R2_BUCKET_ORIGINALS string originals Bucket for source images
IMGX_R2_BUCKET_VARIANTS string variants Bucket for cached transformed variants (L2 cache)

Transform limits

Variable Type Default Description
IMGX_TRANSFORM_MAX_WIDTH u32 8192 Maximum output width in pixels
IMGX_TRANSFORM_MAX_HEIGHT u32 8192 Maximum output height in pixels
IMGX_TRANSFORM_DEFAULT_QUALITY u8 80 Default JPEG/WebP/AVIF quality when q is not specified
IMGX_TRANSFORM_MAX_PIXELS u64 71000000 Maximum total pixel count (width x height). Images exceeding this are rejected.
IMGX_TRANSFORM_STRIP_METADATA bool true Strip EXIF and other metadata from output. Accepts true/1 or false/0.
IMGX_TRANSFORM_MAX_FRAMES u32 100 Maximum frames to load from animated images. Excess frames are truncated.
IMGX_TRANSFORM_MAX_ANIMATED_PIXELS u64 50000000 Maximum total pixels across all frames. Animated images exceeding this budget are served as a static first frame.

Cache

Variable Type Default Description
IMGX_CACHE_ENABLED bool true Enable the in-memory L1 cache. When disabled, every request fetches from origin and is served uncached.
IMGX_CACHE_MAX_SIZE_BYTES usize 536870912 (512 MiB) Maximum memory for the L1 cache. Entries are evicted using LRU when exceeded; entries larger than the limit are served but not cached.
IMGX_CACHE_DEFAULT_TTL_SECONDS u32 3600 TTL for Cache-Control: public, max-age= headers on image responses

Validation

imgx validates configuration at startup and refuses to start if:

  • IMGX_SERVER_PORT is 0
  • IMGX_SERVER_REQUEST_TIMEOUT_MS or IMGX_ORIGIN_TIMEOUT_MS is 0
  • IMGX_TRANSFORM_MAX_WIDTH or IMGX_TRANSFORM_MAX_HEIGHT is 0
  • IMGX_TRANSFORM_DEFAULT_QUALITY is outside 1–100
  • IMGX_ORIGIN_TYPE=http and IMGX_ORIGIN_BASE_URL is empty
  • IMGX_ORIGIN_TYPE=r2 and any R2 field is empty

Logging

Read directly from the environment at startup (not part of Config, so there's no IMGX_ prefix):

Variable Description
RUST_LOG Standard tracing/env_logger-style filter, e.g. RUST_LOG=debug or RUST_LOG=info,imgx=debug. Defaults to info if unset.
IMGX_LOG_FORMAT=json Structured JSON log lines instead of human-readable text — useful for log-shipping pipelines (Cloud Logging, Loki, etc.) that parse structured fields. Any other value (or unset) keeps the default text format.

Example .env file

# Origin
IMGX_ORIGIN_TYPE=r2

# R2
IMGX_R2_ENDPOINT=https://0bc82bff4439c556f9dc1b054d2de6d7.r2.cloudflarestorage.com
IMGX_R2_ACCESS_KEY_ID=your-access-key
IMGX_R2_SECRET_ACCESS_KEY=your-secret-key
IMGX_R2_BUCKET_ORIGINALS=originals
IMGX_R2_BUCKET_VARIANTS=variants

# Server
IMGX_SERVER_PORT=8080
IMGX_SERVER_HOST=0.0.0.0

# Cache
IMGX_CACHE_ENABLED=true
IMGX_CACHE_MAX_SIZE_BYTES=536870912
IMGX_CACHE_DEFAULT_TTL_SECONDS=3600

# Transform limits
IMGX_TRANSFORM_DEFAULT_QUALITY=80
IMGX_TRANSFORM_STRIP_METADATA=true
IMGX_TRANSFORM_MAX_FRAMES=100
IMGX_TRANSFORM_MAX_ANIMATED_PIXELS=50000000