Clearplane 1.0.0-alpha4

· Prerelease

Highlights

Alpha4 gives policies stable system names for Docker label references, adds a configurable upstream inactivity timeout with a 60-second default, and fixes the browser setup validation crash. Optional Cloud integration and error reporting are available with both switches off by default.

Changes

  • Give each policy an editable System name, generated from its name on creation. System names use lowercase ASCII letters, digits, and single internal dashes, and are unique within each policy family. Renaming a saved policy preserves its system name and label references.
  • Resolve clearplane.proxy.<family>.policy labels by system name. Names entered through the UI or API now accept only ASCII letters and digits (A–Z, a–z, 0–9).
  • Use 60 seconds of upstream inactivity when no explicit timeout is configured. Set clearplane.proxy.activity-timeout-seconds from 1 to 86400 to override it. The timer resets when request or response data moves, so active streams can run longer than the timeout.
  • Add Settings → Cloud with the installation ID, connection status, and separate controls for Cloud integration, telemetry consent, and error reporting. No Clearplane account is required to connect an installation.
  • Send bounded error metadata from Core, Edge, the UI host, and ContainerProxy only after Cloud integration and Error reporting are enabled. Reports include the installation ID, component, version, exception type, and stack method names; they exclude message text, request content, credentials, and file paths. Saving an opt-out clears pending reports and stops further uploads.
  • Await asynchronous password-policy validation in forms, including initial setup. Prevent duplicate submissions while validation or submission is pending, and allow retry after validation errors.

Upgrade instructions

Use the alpha4 release's compose.yaml and update any explicit image pins or CLEARPLANE_IMAGE_TAG setting to 1.0.0-alpha4 for all four services. Preserve your overrides, named volumes, service aliases, databases, keys, and certificates. If upgrading from alpha2 or earlier, also read the alpha3 upgrade instructions.

Update existing policy label references when upgrading. Core generates system names for existing policies while preserving their display names and route assignments. Spaces and punctuation become dashes, and collisions receive a suffix. After migration, check the System name column in the UI for each custom policy, update the corresponding labels, and recreate the affected application containers. Display names are no longer accepted as policy references.

For management routes, replace old display-name references in Compose overrides with these values. The alpha4 release's Compose file already uses them:

labels:
  clearplane.proxy.access-control.policy: "clearplane-management-access"
  clearplane.proxy.rate-limit.policy: "clearplane-management-rate-limit"
  clearplane.proxy.auto-ban.policy: "clearplane-management-auto-ban"
  clearplane.proxy.request-headers.policy: "clearplane-management-request-headers"
  clearplane.proxy.response-headers.policy: "clearplane-management-response-headers"

Existing UI/API policy names containing spaces or punctuation need a valid name when edited. Their system names stay unchanged unless explicitly edited; changing a system name also requires updating its labels. See policy names.

Review upstreams that can remain idle for more than 60 seconds. Explicit UI/API timeouts remain in effect; label-owned routes can set a longer limit, for example:

labels:
  clearplane.proxy.activity-timeout-seconds: "300"

Validate and update the deployment:

docker compose config --quiet &&
docker compose pull &&
docker compose up -d --wait

Core applies forward migrations for policy system names and Cloud reporting storage. Cloud integration and Error reporting remain off after upgrade. The installation ID stays unchanged. If you enable Cloud, read the data and consent details; Core stores a signing key in its persistent data directory, which must stay with the installation database.

Reload the management UI after updating so the browser loads the setup validation fix.

Known issues

  • Telemetry saves consent only; telemetry collection is not available. Cloud Protection remains unavailable for Community, Business, and Enterprise. Cloud connectivity is optional and local protection remains available without it.
  • Alpha downloads and images require an authorized GitHub account. The supported target remains one Linux Docker host on x64 or arm64; high availability, multiple hosts, and rolling upgrades remain unavailable.
  • A supported matched backup and restore workflow is unavailable. Downgrading image tags does not roll back database migrations.
  • Native WAF inspection and Basic/JWT authentication for proxied applications remain outside the supported alpha evaluation scope. Forward authentication and client-certificate authentication for customer routes are not implemented in this release.

Release downloads · Changes since alpha3