Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Getting started

Build from source

# Requires: Zig 0.14+, libvips, glib headers
zig build -Doptimize=ReleaseSafe

This produces a binary at zig-out/bin/zimgx.

Configure an origin

Tell zimgx 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 ZIMGX_ORIGIN_TYPE=http
export ZIMGX_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 ZIMGX_ORIGIN_TYPE=r2
export ZIMGX_R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
export ZIMGX_R2_ACCESS_KEY_ID=your-access-key
export ZIMGX_R2_SECRET_ACCESS_KEY=your-secret-key
export ZIMGX_R2_BUCKET_ORIGINALS=my-images

Start the server

./zig-out/bin/zimgx
# 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/photos/hero.jpg
 
# Resize to 400px wide
curl http://localhost:8080/photos/hero.jpg/w=400
 
# Resize and convert to WebP at quality 85
curl http://localhost:8080/photos/hero.jpg/w=800,f=webp,q=85

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

Use Docker instead

Skip the build step entirely:

docker pull ghcr.io/officialunofficial/zimgx:latest
 
docker run -p 8080:8080 \
  -e ZIMGX_ORIGIN_TYPE=http \
  -e ZIMGX_ORIGIN_BASE_URL=https://images.example.com \
  ghcr.io/officialunofficial/zimgx:latest

Caching

zimgx 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 ZIMGX_CACHE_ENABLED=true
export ZIMGX_CACHE_MAX_SIZE_BYTES=536870912   # 512 MiB
export ZIMGX_CACHE_DEFAULT_TTL_SECONDS=3600   # 1 hour Cache-Control

zimgx 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
curl http://localhost:8080/metrics
# Request counts, cache hit/miss rates, uptime

Next steps