Configuration

Configuration #

This is the unified documentation, please use the latest version of WebP Server Go if possible as some configuration might not be available in previous versions.

WebP Server Go can be configured by the following ways:

  • config.json file
  • Environment variables

Priority: Environment variables > config.json file.

Configuration changelog #

  • MAX_CACHE_SIZE is added at version 0.12.0
  • EXTRA_PARAMS_CROP_INTERESTING is added at version 0.11.2
  • STRIP_METADATA, CONVERT_TYPES is added at version 0.11.0, dropped ENABLE_AVIF entry.
  • CACHE_TTL is added at version 0.10.7
  • READ_BUFFER_SIZE, CONCURRENCY and DISABLE_KEEPALIVE is added at version 0.9.12

Full configuration #

This is the full configuration with default values of WebP Server Go(except the IMG_MAP part), you can copy it to config.json and modify it to your needs, or if you just want to change some of the values, you can use environment variables to override the specific values.

You can use environment variables to override the configuration in config.json, the environment variables are added by using prefix WEBP_ and uppercase the field name, for example, HOST will be WEBP_HOST, IMG_PATH will be WEBP_IMG_PATH.

WEBP_ALLOWED_TYPES are separated by ,, for example, WEBP_ALLOWED_TYPES=jpg,png,webp. WEBP_CONVERT_TYPES are separated by ,, for example, WEBP_CONVERT_TYPES=webp,avif,jxl.

{
  "HOST": "0.0.0.0",
  "PORT": "3333",
  "QUALITY": "80",
  "IMG_PATH": "./pics",
  "EXHAUST_PATH": "./exhaust",
  "IMG_MAP": {},
  "ALLOWED_TYPES": ["jpg", "png", "jpeg", "bmp", "gif", "svg", "heic", "nef", "webp"],
  "CONVERT_TYPES": ["webp"],
  "STRIP_METADATA": true,
  "ENABLE_EXTRA_PARAMS": false,
  "EXTRA_PARAMS_CROP_INTERESTING": "InterestingAttention",
  "READ_BUFFER_SIZE": 4096,
  "CONCURRENCY": 262144,
  "DISABLE_KEEPALIVE": false,
  "CACHE_TTL": 259200,
  "MAX_CACHE_SIZE": 0
}

The IMG_MAP example as below:

"IMG_MAP": {
  "/2": "./pics2",
  "/3": "./pics3",
  "http://www.example.com": "https://docs.webp.sh"
}

Description of each field:

FieldEnvironment variablesTypeDescription
HOSTWEBP_HOSTstringHost to listen on
PORTWEBP_PORTstringPort to listen on
QUALITYWEBP_QUALITYstringQuality of image, from 0 to 100, 100 means lossless conversion.
IMG_PATHWEBP_IMG_PATHstringPath to the image directory(of original images), if you’d like to use a remote backend(such as external Nginx served static site, Aliyun OSS or Tencent COS), please refer to Remote Backend.
EXHAUST_PATHWEBP_EXHAUST_PATHstringPath to the cache directory(of WebP images), for example, with EXHAUST_PATH set to /var/cache/webp, your webp image will be saved at /var/cache/webp/pics/tsuki.jpg.1582558990.webp.
IMG_MAP/dictMap of URI/Host to image, if this is present then IMG_PATH will be ignored, see more on MultiPath page
ALLOWED_TYPESWEBP_ALLOWED_TYPESlistList of allowed image types, if you’d like to allow all image types, just use ["*"] here.
CONVERT_TYPESWEBP_CONVERT_TYPESstringThe image types list that WebP Server will try to convert to, default is ["webp"] which means it will only try to convert image to WebP, available options: ["webp","avif","jxl"].
STRIP_METADATAWEBP_STRIP_METADATAboolWhether to Strip EXIF metadata from images.
ENABLE_EXTRA_PARAMSWEBP_ENABLE_EXTRA_PARAMSboolMeans whether to enable Extra Parameters, basically it allows you to do some transform on images like https://img.webp.sh/path/tsuki.jpg?width=20, you can find more info on Extra Parameters page.
EXTRA_PARAMS_CROP_INTERESTINGWEBP_EXTRA_PARAMS_CROP_INTERESTINGstringDefines how should WebP Server crop image when ENABLE_EXTRA_PARAMS is on and image requests contains both width and height, available options are: “InterestingNone”, “InterestingEntropy”, “InterestingCentre”, “InterestingAttention”, “InterestringLow”, “InterestingHigh”, “InterestingAll”, you can find more info on Extra Parameters page.
READ_BUFFER_SIZEWEBP_READ_BUFFER_SIZEnumberper-connection buffer size for requests’ reading. This also limits the maximum header size.
Increase this buffer if your clients send multi-KB RequestURIs and/or multi-KB headers (for example, BIG cookies).
CONCURRENCYWEBP_CONCURRENCYnumberMaximum number of concurrent connections
DISABLE_KEEPALIVEWEBP_DISABLE_KEEPALIVEstringDisable keep-alive connections, the server will close incoming connections after sending the first response to the client
CACHE_TTLWEBP_CACHE_TTLnumberCache TTL (minutes) for Remote Backends(Proxy Mode)
We use HEAD request to get remote image info, so your backend needs to support HEAD request, after first successfully HEAD request, it will be cached for CACHE_TTL minutes, during that period, we will not send HEAD request again and use local cache for rendering.
Setting this value to 0 means cache forever.
MAX_CACHE_SIZEWEBP_MAX_CACHE_SIZEnumberWith unit of MiB, the default value is 0, which not clean local cached files, if this value is set, for example 50, then a background task will run alongside with WebP Server Go once per minute to make sure the local cached directories(./metadata, ./exhaust and ./remote-raw(if using remote backend)) will be below 50MiB, seperately.

Configuration example #

Suppose your website and image has the following pattern:

Image PathWebsite Path
/var/www/img.webp.sh/path/tsuki.jpghttps://img.webp.sh/path/tsuki.jpg

And you wish to enable Extra Parameters, then

  • ./pics should be changed to /var/www/img.webp.sh
  • ./exhaust is cache folder for output images, by default it will be in exhaust directory alongside with docker-compose.yml file, if you’d like to keep cached images in another folder as , you can change ./exhaust to /some/other/path/to/exhaust
  • ENABLE_EXTRA_PARAMS can be passed in by environment variable WEBP_ENABLE_EXTRA_PARAMS=true

Your docker-compose.yml file can be written as follows:

version: '3'

services:
  webp:
    image: webpsh/webp-server-go
    restart: always
    environment:
      - WEBP_ENABLE_EXTRA_PARAMS=true
    volumes:
      - /var/www/img.webp.sh:/opt/pics
      - ./exhaust:/opt/exhaust
      - ./metadata:/opt/metadata
    ports:
      - 127.0.0.1:3333:3333