Skip to main content

Profiles and configuration

Multiple profiles in one process​

A profile connects an image source, processing settings and a cache pool. One profile can read a Bitrix directory while another reads allowlisted HTTPS sources.

Configuration is loaded at startup. Restart the service after changing YAML; hot reload is not supported.

Quality and format​

defaults:
  processing:
    output: auto
    webp: {quality: 80, effort: 4}
    avif: {quality: 55, effort: 2}
  http:
    fallback: original
    browser_max_age: 604800

output: auto negotiates the format through Accept. Higher effort typically requires more CPU time. Tune quality using real images from your website.

Image dimensions

Processing preserves dimensions, applies EXIF orientation and preserves transparency. URL parameters such as w, h, fit and crop are not part of the current API.

Local source files​

profiles:
  bitrix:
    source: {type: file, root: /mnt/upload}
    cache: local
routes:
  - {path_prefix: /upload/, profile: bitrix, type: file}

cache: local must reference an existing cache_pools.local. Profile names appear in the standard /v1/{profile}/... routes.

Paths are resolved relative to root. Symlinks are prohibited in path components. Do not use your entire filesystem as a source root.

HTTPS sources​

profiles:
  remote:
    source:
      type: https
      allowed_hosts: [images.example.com]
      revalidate_after: 300s
    cache: local

Use exact hostnames in the allowlist. The service validates DNS, public addresses, certificates and every redirect. Private IPs, userinfo in URLs and HTTP image sources are prohibited.

revalidate_after controls source revalidation; upstream Cache-Control, Age and Expires can shorten the interval. Test S3 settings do not enable HTTP for image sources.

Validate changes​

Keep a copy of the working configuration, change one profile and restart a test instance. Check /ready, requests to each source and startup logs. A complete minimal example is included in the quick start.