Skip to content
LogoLogo

Getting started

Build from source

# Requires: Rust (stable), libvips, glib headers
cargo build --release -p imgx

This produces a binary at target/release/imgx.

Configure an origin

Tell imgx where your images live. Pick one of the following options.

HTTP origin

Use this if your images are behind any web server, S3 presigned URLs, or an existing CDN:

export IMGX_ORIGIN_TYPE=http
export IMGX_ORIGIN_BASE_URL=https://my-bucket.s3.amazonaws.com

S3/R2 origin

Use this for direct bucket access with any S3-compatible storage — Cloudflare R2, AWS S3, DigitalOcean Spaces, MinIO, and others:

export IMGX_ORIGIN_TYPE=r2
export IMGX_R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
export IMGX_R2_ACCESS_KEY_ID=your-access-key
export IMGX_R2_SECRET_ACCESS_KEY=your-secret-key
export IMGX_R2_BUCKET_ORIGINALS=my-images

Start the server

./target/release/imgx
# Listening on 0.0.0.0:8080

Request an image

Assuming your origin has a file at the key photos/hero.jpg:

# Original, no transforms
curl http://localhost:8080/image/photos/hero.jpg
 
# Resize to 400px wide
curl http://localhost:8080/image/w=400/photos/hero.jpg
 
# Resize and convert to WebP at quality 85
curl http://localhost:8080/image/w=800,f=webp,q=85/photos/hero.jpg

No upload API. No database. Your images stay where they are.

Use Docker instead

Skip the build step entirely:

docker pull ghcr.io/officialunofficial/imgx:latest
 
docker run -p 8080:8080 \
  -e IMGX_ORIGIN_TYPE=http \
  -e IMGX_ORIGIN_BASE_URL=https://images.example.com \
  ghcr.io/officialunofficial/imgx:latest

Caching

imgx caches transformed images automatically. Repeated requests skip the origin fetch and transformation step entirely.

In-memory (default): A 512 MiB LRU cache with no setup required.

Tiered (memory plus R2): A fast memory layer backed by persistent R2 storage.

export IMGX_CACHE_ENABLED=true
export IMGX_CACHE_MAX_SIZE_BYTES=536870912   # 512 MiB
export IMGX_CACHE_DEFAULT_TTL_SECONDS=3600   # 1 hour Cache-Control

imgx generates ETags automatically. Clients that send If-None-Match receive 304 Not Modified responses, saving bandwidth.

Health and monitoring

# Health check
curl http://localhost:8080/health
# {"status":"ok"}
 
# Readiness probe
curl http://localhost:8080/ready
# {"ready":true}
 
# Server metrics (Prometheus exposition format)
curl http://localhost:8080/metrics
# Request counts, cache hit/miss rates, uptime

Next steps