Skip to main content

Add a Watermark to Images

About the watermark feature

What is it? Watermark overlays a PNG image onto every processed image, either as a single badge in the bottom-right corner or tiled across the whole image.

Enable watermarking

Watermark is included in the Image Optimizer service. Configure via environment variables.

WATERMARK_ENABLED=true
WATERMARK_B64=<base64-encoded PNG>
WATERMARK_POSITION=bottom_right   # or: repeated
VariableTypeDefaultDescription
WATERMARK_ENABLEDbooleantrueEnable or disable watermark overlay
WATERMARK_B64string(none)Base64-encoded PNG image to use as the watermark
WATERMARK_POSITIONstringbottom_rightWatermark placement: bottom_right or repeated

When WATERMARK_ENABLED is true and WATERMARK_B64 contains a valid base64-encoded PNG, the watermark is applied to every processed image with the following defaults:

  • Scale: 18% of the image width
  • Opacity: 60%
  • Margin: 12 px from the edge

Watermark positioning

  • bottom_right (default) — places a single watermark in the bottom-right corner with the configured margin.
  • repeated — tiles the watermark in a grid across the entire image. Each tile is spaced by the watermark size plus the margin.

If WATERMARK_B64 is missing or invalid, the watermark step is skipped gracefully and the image is served without it.

Generating WATERMARK_B64

base64 -w0 watermark.png > watermark_b64.txt

Then set the environment variable to the contents of that file:

WATERMARK_B64="$(cat watermark_b64.txt)"

Check HTTP headers

curl -I https://your-cdn.com/image.jpg

Expected: X-Img-Operations includes watermarking.

Limitations

  • Watermark is skipped (without failing the request) if WATERMARK_B64 is missing or cannot be decoded as a PNG.
  • Watermark is skipped if it is larger than the base image after scaling.

Troubleshooting

Watermark not applied: Verify WATERMARK_ENABLED=true and WATERMARK_B64 is a valid base64-encoded PNG. Watermark in wrong position: Check WATERMARK_POSITION is bottom_right or repeated.

WATERMARK_ENABLED=true
WATERMARK_POSITION=bottom_right