README
¶
TransformImgs
Open Source Image CDN that provides image transformation API and supports the latest image formats, such as WebP, AVIF, Jpeg XL, and network client hints.
Table of Contents
- Why?
- Features
- Quickstart
- API
- Running
- SaaS
- Performance tests
- Opened tickets for images related features
- Contribute
- License
- Todo
Why?
We wrote a big blog on this, and here is TLDR:
Transformimgs is an image CDN for Web, so API must cover typical use cases, like thumbnails, zoom in product images, etc. Any new API endpoints must solve the above problems.
The goal is to have zero-config API that makes decisions based on the input, so you don't need to provide additional parameters like quality, output format, type of compression, etc.
Therefore, this allows you to configure the integration once. New features, like new image formats, will work with your front end automatically without any changes.
To achieve that goal we should keep API to bare minimum and hide the smartness in the implementation.
Features
- Resize/optimises/crops raster (PNG and JPEG) images.
- JpegXL / AVIF / WebP support based on "Accept" header.
- Vary header support - ready to deploy behind any CDN.
- Responsive images support including high DPI (retina) displays
- Save-Data support
Quickstart
There is an example of running API behind reverse proxy with integration example in quickstart/ folder.
To run:
cd quickstart
docker-compose up
open https://localhost
API
The API has 4 HTTP endpoints:
- /img/{IMG_URL}/optimise - optimises image
- /img/{IMG_URL}/resize - resizes image
- /img/{IMG_URL}/fit - resize image to the exact size by resizing and cropping it
- /img/{IMG_URL}/asis - returns original image
Docs:
- Swagger-UI - use API key
MjUyMTM3OTQyNw__which allows to transform any image from unsplash.com - OpenAPI spec
Running Locally
Docker
The latest docker image published on Docker hub
Starting the server:
$ docker run -p 8080:8080 pixboost/transformimgs [OPTIONS]
To verify:
- Health check:
curl http://localhost:8080/health - Transformation:
open http://localhost:8080/img/https://images.unsplash.com/photo-1591769225440-811ad7d6eab3/resize?size=600
Options
Everything below is optional and have sensible defaults.
| Option | Description | Default |
|---|---|---|
| cache | Number of seconds to cache image(0 to disable cache). Used in max-age HTTP response. | 2592000 (30 days) |
| proc | Number of images processors to run. | Number of CPUs (cores) |
| disableSaveData | If set to true then will disable Save-Data client hint. Should be disabled on CDNs that don't support Save-Data header in Vary. | false |
Running from source code
Prerequisites:
- Go 1.18+ with modules support
- Installed imagemagick v7.0.25+ with AVIF support in
/usr/local/bin
$ git clone git@github.com:Pixboost/transformimgs.git
$ cd transformimgs
$ ./run.sh
Using from Go Web Application
You could also easily plugin HTTP route into your existing web application using service.GetRouter method. Here is a quick example of how to do that.
SaaS
We run SaaS version at pixboost.com with generous free tier.
Perks of SaaS version:
- CDN with HTTP/3 support included
- Dashboard with usage monitor
- API Key support with domains allow list
- AWS S3 integration
- API workflows for cache busting and warmup
- Version upgrades
Go modules have been introduced in v6.
Performance tests
There is a JMeter performance test you can run against a service. To run tests:
- Start a performance test environment:
$ docker-compose -f docker-compose-perf.yml up
- Run JMeter tests:
$ jmeter -n -t perf-test.jmx -l ./results.jmx -e -o ./results
- Run JMeter WebP test:
$ jmeter -n -t perf-test-webp.jmx -l ./results-webp.jmx -e -o ./results-webp
- Run JMeter AVIF test:
$ jmeter -n -t perf-test-avif.jmx -l ./results-avif.jmx -e -o ./results-avif
- Run JMeter JPEG XL test:
$ jmeter -n -t perf-test-jxl.jmx -l ./results-jxl.jmx -e -o ./results-jxl
Opened tickets for images related features
- Safari to support Save-Data
- Auto sizes for lazy loaded img in Firefox
- Auto sizes for lazy loaded img in Safari
Contribute
Shout out with any ideas. PRs are more than welcome.
License
Todo
Add JpegXR support(IE supports WEBP)Add Jpeg 2000 support(Safari support WEBP)- Client Hints - on hold due to browsers adoption
Save-Data header(Added in version 7.0.0)- SVG support
- Consider using Zopfli or Brotli for PNGs
JpegXL Support since supported by Safari 17(Added in version 8.12.0)GIF support(Added in version 6.1.0)
Documentation
¶
Overview ¶
Package transformimgs provides an easy way to add image transformations into your web applications.
Package provides simple API that manipulating images and deliver them using next generation formats, including AVIF and JpegXL.
You could use the package to plugin into the existing Go web application using img.Service.GetRouter method or deploy as a standalone web app using docker image.
Example ¶
package main
import (
"fmt"
"github.com/Pixboost/transformimgs/v8/img"
"github.com/Pixboost/transformimgs/v8/img/loader"
"github.com/Pixboost/transformimgs/v8/img/processor"
"log"
"net/http"
"net/http/httptest"
"runtime"
)
func main() {
l := &loader.Http{}
p, err := processor.NewImageMagick("/usr/local/bin/convert", "/usr/local/bin/identify")
if err != nil {
log.Fatal(err)
}
s, err := img.NewService(l, p, runtime.NumCPU())
if err != nil {
log.Fatal(err)
}
// s.GetRouter() is ready to use in your web server
server := httptest.NewServer(s.GetRouter())
defer server.Close()
resizeApi := fmt.Sprintf("%s/img/https://raw.githubusercontent.com/Pixboost/transformimgs/main/quickstart/site/img/parrot-lossy.jpg/resize?size=600", server.URL)
resp, err := http.Get(resizeApi)
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Status)
}
Output: 200 OK
Source Files
Directories