Configuration

zimgx reads all configuration from environment variables prefixed with ZIMGX_. Every variable is optional and has a sensible default.

Server

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

Origin

Variable	Type	Default	Description
`ZIMGX_ORIGIN_TYPE`	`string`	`http`	`http` fetches from `ZIMGX_ORIGIN_BASE_URL`. `r2` fetches from an R2 bucket.
`ZIMGX_ORIGIN_BASE_URL`	`string`	`http://localhost:9000`	Base URL for the HTTP origin. The image path is appended to this value.
`ZIMGX_ORIGIN_TIMEOUT_MS`	`u32`	`10000`	Timeout (ms) for origin fetch requests
`ZIMGX_ORIGIN_MAX_RETRIES`	`u8`	`2`	Retry attempts for failed origin fetches
`ZIMGX_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.

R2/S3

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

Variable	Type	Default	Description
`ZIMGX_R2_ENDPOINT`	`string`	`""`	R2/S3-compatible endpoint URL
`ZIMGX_R2_ACCESS_KEY_ID`	`string`	`""`	Access key ID
`ZIMGX_R2_SECRET_ACCESS_KEY`	`string`	`""`	Secret access key
`ZIMGX_R2_BUCKET_ORIGINALS`	`string`	`originals`	Bucket for source images
`ZIMGX_R2_BUCKET_VARIANTS`	`string`	`variants`	Bucket for cached transformed variants (L2 cache)

Transform limits

Variable	Type	Default	Description
`ZIMGX_TRANSFORM_MAX_WIDTH`	`u32`	`8192`	Maximum output width in pixels
`ZIMGX_TRANSFORM_MAX_HEIGHT`	`u32`	`8192`	Maximum output height in pixels
`ZIMGX_TRANSFORM_DEFAULT_QUALITY`	`u8`	`80`	Default JPEG/WebP/AVIF quality when `q` is not specified
`ZIMGX_TRANSFORM_MAX_PIXELS`	`u64`	`71000000`	Maximum total pixel count (width x height). Images exceeding this are rejected.
`ZIMGX_TRANSFORM_STRIP_METADATA`	`bool`	`true`	Strip EXIF and other metadata from output. Accepts `true`/`1` or `false`/`0`.
`ZIMGX_TRANSFORM_MAX_FRAMES`	`u32`	`100`	Maximum frames to load from animated images. Excess frames are truncated.
`ZIMGX_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
`ZIMGX_CACHE_ENABLED`	`bool`	`true`	Enable the in-memory L1 cache. When disabled, every request fetches from origin.
`ZIMGX_CACHE_MAX_SIZE_BYTES`	`usize`	`536870912` (512 MiB)	Maximum memory for the L1 cache. Entries are evicted using LRU when exceeded.
`ZIMGX_CACHE_DEFAULT_TTL_SECONDS`	`u32`	`3600`	TTL for `Cache-Control: public, max-age=` headers on image responses

Validation

zimgx validates configuration at startup and refuses to start if:

ZIMGX_SERVER_PORT is 0
ZIMGX_SERVER_REQUEST_TIMEOUT_MS or ZIMGX_ORIGIN_TIMEOUT_MS is 0
ZIMGX_TRANSFORM_MAX_WIDTH or ZIMGX_TRANSFORM_MAX_HEIGHT is 0
ZIMGX_TRANSFORM_DEFAULT_QUALITY is outside 1–100
ZIMGX_ORIGIN_TYPE=http and ZIMGX_ORIGIN_BASE_URL is empty
ZIMGX_ORIGIN_TYPE=r2 and any R2 field is empty

Example .env file

# Origin
ZIMGX_ORIGIN_TYPE=r2
 
# R2
ZIMGX_R2_ENDPOINT=https://0bc82bff4439c556f9dc1b054d2de6d7.r2.cloudflarestorage.com
ZIMGX_R2_ACCESS_KEY_ID=your-access-key
ZIMGX_R2_SECRET_ACCESS_KEY=your-secret-key
ZIMGX_R2_BUCKET_ORIGINALS=originals
ZIMGX_R2_BUCKET_VARIANTS=variants
 
# Server
ZIMGX_SERVER_PORT=8080
ZIMGX_SERVER_HOST=0.0.0.0
 
# Cache
ZIMGX_CACHE_ENABLED=true
ZIMGX_CACHE_MAX_SIZE_BYTES=536870912
ZIMGX_CACHE_DEFAULT_TTL_SECONDS=3600
 
# Transform limits
ZIMGX_TRANSFORM_DEFAULT_QUALITY=80
ZIMGX_TRANSFORM_STRIP_METADATA=true
ZIMGX_TRANSFORM_MAX_FRAMES=100
ZIMGX_TRANSFORM_MAX_ANIMATED_PIXELS=50000000