Configure Plone settings

plone.pgthumbor reads its configuration from environment variables. A Plone registry schema (IThumborSettings) is also available for settings that do not change per deployment.

Environment variables always take precedence over registry values.

Environment variables

Set these before starting Zope.

PGTHUMBOR_SERVER_URL (required)

The public, browser-facing URL of the Thumbor server. Plone uses this as the base URL when generating image src attributes. It must be reachable from the end user’s browser:

export PGTHUMBOR_SERVER_URL="https://example.com/thumbor"

In the Docker example stack, nginx proxies /thumbor/ to the Thumbor container, so the value is:

export PGTHUMBOR_SERVER_URL="http://localhost:8080/thumbor"

A trailing slash is stripped automatically.

If this variable is empty, plone.pgthumbor is effectively disabled – the @@images view falls back to default Plone scaling behavior.

PGTHUMBOR_SECURITY_KEY (required unless unsafe mode)

The HMAC-SHA1 key used to sign Thumbor URLs. Must match the SECURITY_KEY in thumbor.conf:

export PGTHUMBOR_SECURITY_KEY="your-strong-random-key"

If neither PGTHUMBOR_SECURITY_KEY nor PGTHUMBOR_UNSAFE is set, plone.pgthumbor logs a warning and disables itself.

PGTHUMBOR_UNSAFE

Enable unsigned /unsafe/ URLs. Development only.

export PGTHUMBOR_UNSAFE="true"

Accepted values: true, 1, yes (case-insensitive). All other values are treated as false.

When enabled, Plone generates unsigned URLs prefixed with /unsafe/ instead of an HMAC signature. Thumbor must also have ALLOW_UNSAFE_URL = True for these to work.

Warning

Never enable unsafe mode in production. It allows anyone to request arbitrary image transformations, consuming server resources and potentially exposing private images.

Plone registry settings

The IThumborSettings registry schema provides the following fields. They serve as fallback values when the corresponding environment variable is not set. Configure them in Site Setup > Thumbor Settings or programmatically via the Plone registry.

server_url

Thumbor server URL. Same role as PGTHUMBOR_SERVER_URL. The environment variable takes precedence.

  • Type: TextLine

  • Default: "" (empty)

security_key

Shared HMAC key. Same role as PGTHUMBOR_SECURITY_KEY. The environment variable takes precedence.

  • Type: TextLine

  • Default: "" (empty)

unsafe

Unsafe mode. Same role as PGTHUMBOR_UNSAFE. The environment variable takes precedence.

  • Type: Bool

  • Default: False

smart_cropping

Enable Thumbor smart cropping. When enabled, Plone appends the /smart/ filter to Thumbor URLs. Thumbor uses OpenCV-based face and feature detection to choose a focal point for cropping.

  • Type: Bool

  • Default: False

paranoid_mode

When enabled, every image request includes the content object’s ZOID in the Thumbor URL path (3-segment format: <blob_zoid>/<tid>/<content_zoid>). Thumbor’s auth_handler then verifies with Plone that the requesting user has View permission on the content object.

When disabled (default), only images on non-public content use the 3-segment format. Public images use the 2-segment format and skip the auth check for better performance.

  • Type: Bool

  • Default: False

Configuration precedence

The configuration is resolved in plone.pgthumbor.config.get_thumbor_config():

Environment variables are checked first. 2. If PGTHUMBOR_SERVER_URL is empty, the function returns None (Thumbor integration disabled). 3. If neither PGTHUMBOR_SECURITY_KEY nor PGTHUMBOR_UNSAFE is set, a warning is logged and the function returns None.

Example: Docker Compose

In a Docker Compose file, set the environment on the Plone service:

plone:
  environment:
    PGTHUMBOR_SERVER_URL: "http://localhost:8080/thumbor"
    PGTHUMBOR_SECURITY_KEY: "your-strong-random-key"

Example: systemd unit

In a systemd service file:

[Service]
Environment="PGTHUMBOR_SERVER_URL=https://example.com/thumbor"
Environment="PGTHUMBOR_SECURITY_KEY=your-strong-random-key"