Wip/show what changed in 2x

website/docs/docs/on-premises.md

@@ -9,6 +9,7 @@ sidebar_label: Architecture
 
 * An application server capable of running Docker
 * PostgreSQL database
+* Redis Serialization Protocol (RESP)-compatible key/value cache
 * SAML IDP for SSO
 * PactFlow license file
 
@@ -18,31 +19,37 @@ sidebar_label: Architecture
 
 ### Example AWS deployment using ECS
 
-![System architecture](/img/saas-architecture-aws.png)
+![System architecture](/img/on-prem-architecture-2x.png)
 
 ## Internal architecture
 
 The PactFlow On-Premises application is distributed as a Docker image. It is based on the open source [Pact Broker](https://github.com/pact-foundation/pact_broker), which is a Ruby application.
 
 ### Application user requirements
 
-The PactFlow application does not need any elevated privileges to run. It runs under the user `app:app`.
+You can run the application without elevated privileges. It runs under the user `app`.
 
 ### Application port
 
 The PactFlow application runs on port `9292` by default. This can be configured by setting the [PACTFLOW_HTTP_PORT](/docs/on-premises/environment-variables#pactflow_http_port) environment variable.
 
 ### Healthcheck endpoint
 
-A healthcheck endpoint for use by a Docker container managment service is available at `http://<HOST>/diagnostic/status/heartbeat`. No authentication is required. This endpoint does not make a connection to the database.
+There's a healthcheck endpoint at `http://<HOST>/diagnostic/status/heartbeat` meant for Docker container management tools.
 
-If the healthcheck is running from inside the container, make sure to use the port defined in the environment variable `$PACTFLOW_HTTP_PORT`, which defaults to 9292. You can use `wget` to perform the healthcheck request.
+- It doesn't need authentication.
+- It doesn't touch the database.
+- You can use it to check if load balancer targets are working properly.
+
+If you're running the healthcheck from inside the container, be sure to use the port specified by the `$PACTFLOW_HTTP_PORT` environment variable (defaults to `9292` if not set).
+
+You can use `supervisorctl` to send the healthcheck request.
 
 An example healthcheck configuration for Docker Compose:
 
 ```yaml
 healthcheck:
-  test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"]
+  test: ["supervisorctl", "status", "haproxy", "marko", "pactflow"]
   interval: 30s
   timeout: 10s
   retries: 3

website/docs/docs/on-premises/docker-compose-example.md

@@ -35,9 +35,9 @@ Which should produce an output such as:
 ```sh
 > docker images quay.io/pactflow/enterprise
 REPOSITORY                    TAG                 IMAGE ID            CREATED             SIZE
-quay.io/pactflow/enterprise   1.9.0               32db429fda01        7 weeks ago         454MB
-quay.io/pactflow/enterprise   latest              32db429fda01        7 weeks ago         454MB
-quay.io/pactflow/enterprise   1.8.0               7f9b3c3aa50e        3 months ago        462MB
+quay.io/pactflow/enterprise   2.0.0               32db429fda01        1 day ago           462MB # <- this guide applies to 2.x.x version
+quay.io/pactflow/enterprise   latest              32db429fda01        1 day ago           462MB
+quay.io/pactflow/enterprise   1.36.0              7f9b3c3aa50e        7 weeks ago         454MB
 ```
 
 ## 2. PactFlow license file
@@ -56,9 +56,10 @@ version: "3"
 
 services:
   pactflow:
-    image: quay.io/pactflow/enterprise
+    image: quay.io/pactflow/enterprise:latest
     depends_on:
       - postgres
+      - redis
     environment:
       # This is set to localhost for this example but in a real deployment, this needs to be set to the actual URL of the application
       - PACTFLOW_BASE_URL=http://localhost
@@ -71,24 +72,23 @@ services:
       # 'Allow all' for the webhook host whitelist should only be used for demo purposes. See docs for configuring this in production.
       - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/
       - PACTFLOW_HTTP_PORT=9292
+      # Link to the postgres database
       - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres
-      - Short log format only for demo purposes. Use json in production.
-      - PACTFLOW_LOG_FORMAT=short
       - PACTFLOW_LOG_LEVEL=info
       - PACTFLOW_ADMIN_API_KEY=admin
       - PACTFLOW_MASTER_ENCRYPTION_KEY=thisissomerandombytes
       - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret---------
       - PACT_BROKER_ADMIN_API_KEY=admin 
       - PACTFLOW_HTTP_LOGGING_ENABLED=true
+      # Link to the redis cache
+      - REDIS_URL=redis://redis:6379
     ports:
       - "80:9292"
     healthcheck:
-      test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"]
+      test: ["CMD", "supervisorctl", "status", "haproxy", "marko", "pactflow"]
       interval: 30s
       timeout: 10s
       retries: 3
-    entrypoint: dockerize
-    command: -wait tcp://postgres:5432 docker-entrypoint
     volumes:
       - ./pactflow-onprem.lic:/home/pactflow-onprem.lic
 
@@ -103,17 +103,20 @@ services:
       POSTGRES_PASSWORD: password
       POSTGRES_DB: postgres
 
+  redis:
+    image: redis:latest
+
 volumes:
   postgres-volume:
 ```
 
 You can verify all services by running `docker ps`:
 
 ```
-CONTAINER ID        IMAGE                         COMMAND                  CREATED             STATUS                             PORTS                                                    NAMES
-8318130fa98a        quay.io/pactflow/enterprise   "docker-entrypoint"      18 seconds ago      Up 17 seconds (health: starting)   9292/tcp, 0.0.0.0:80->9292/tcp                           tmp_pactflow_1
-7ba5d1679d09        kristophjunge/test-saml-idp   "docker-php-entrypoi…"   7 minutes ago       Up 17 seconds                      0.0.0.0:8080->8080/tcp, 80/tcp, 0.0.0.0:8443->8443/tcp   tmp_simplesaml_1
-c0e3059fa37c        postgres                      "docker-entrypoint.s…"   7 minutes ago       Up 17 seconds (health: starting)   0.0.0.0:5432->5432/tcp                                   tmp_postgres_1
+CONTAINER ID   IMAGE                                          COMMAND                  CREATED          STATUS                    PORTS                  NAMES
+1cefdf8b1e1b   quay.io/pactflow/enterprise:2.0.0              "docker-entrypoint"      24 minutes ago   Up 24 minutes (healthy)   0.0.0.0:80->9292/tcp   tmp_pactflow_1
+6bedae5936dc   redis:latest                                   "docker-entrypoint.s…"   2 hours ago      Up 24 minutes             6379/tcp               tmp_redis_1
+8b393d35a20c   postgres:13-alpine                             "docker-entrypoint.s…"   9 days ago       Up 24 minutes (healthy)   5432/tcp               tmp_postgres_1
 ```
 
 ## 3. Login to PactFlow

website/docs/docs/on-premises/docker-image-registry.md

@@ -14,7 +14,7 @@ If you are on a PactFlow trial, creating a RedHat account is **not** required. Y
 
 To set you up with console access, you will need to create a [RedHat account](https://quay.io/signin/). Choose "Register for a RedHat account" and once comwpleted, provide the username/email address to us to add you to the registry.
 
-Once we have granted access to your given email address, you should receive an email from Red Hat Quay confirming access to the PactFlow organisation.
+Once we have granted access to your given email address, you should receive an email from Red Hat Quay confirming access to the PactFlow organization.
 
 ### CI Access
 
@@ -36,7 +36,7 @@ Once we have created you a new user, you will receive an email from Quay.io invi
 
    ![Completed signup](/on-premises/quay-completed.png)
 
-1. You should now have access to the `enterprise` repository in the `pactflow` organisation.
+1. You should now have access to the `enterprise` repository in the `pactflow` organization.
 
 1. You can now sign in with your account (in addition to your Robot Account) to quay to pull docker images. See [getting started with Quay.io](https://docs.quay.io/solution/getting-started.html) for more on this.
 

website/docs/docs/on-premises/environment-variables.md

@@ -24,15 +24,6 @@ The PactFlow application log level
 **Default:** `INFO`<br/>
 **Allowed values:** `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`<br/>
 
-### PACTFLOW_LOG_FORMAT
-
-The PactFlow application log format
-
-**Required:** false<br/>
-**Default:** `json`<br/>
-**Allowed values:** `json`, `default`, `color`<br/>
-**More information:** https://github.com/rocketjob/semantic_logger/tree/master/lib/semantic_logger/formatters<br/>
-
 ### PACTFLOW_HTTP_LOGGING_ENABLED
 
 When true, HTTP request details and response status and duration will be logged to stdout in json format
@@ -531,7 +522,7 @@ The secret used to encrypt the rack.session cookie.
 To generate an appropriate value, run the following on Linux/Mac:
 
 ```
-env LC_CTYPE=C tr -dc '_A-Z-a-z-0-9!#$%&*+-\\.^_|~' < /dev/urandom | fold -w 32 | head -n 1
+LC_ALL=C tr -dc '_A-Z-a-z-0-9!#$%&*+-\\.^_|~' < /dev/urandom | fold -w 64 | head -n 1
 ```
 
 **Required:** true<br/>
@@ -639,3 +630,17 @@ head < /dev/random -c 16 | base64
 
 **Required:** if `PACTFLOW_API_TOKEN_ENCRYPTION_ENABLED` is set to `true`<br/>
 **Example:** `JUVDdnRzLXZyWHA7UF93RAo=`<br/>
+
+## User Interface
+
+<hr/>
+
+
+
+### PACTFLOW_CLARITY_DISABLED
+
+Disables the new user interface introduced in version 2.0.0. When this environment variable is set, the legacy interface becomes the default and users cannot switch to the new UI.
+
+**Required:** false<br/>
+**Default:** unset<br/>
+**Allowed values:** `true`<br/>

website/docs/docs/on-premises/installation/checklist.md

@@ -27,6 +27,7 @@ Configure the PactFlow On-Premises application in your identity provider. See th
 * Use the [environment variable templates](/docs/on-premises/environment-variables/templates) to create the appropriate deployment configuration artifacts for the PactFlow Docker image (eg. Cloudformation template, Helm chart etc.)
 * Ensure the [compute resources](/docs/on-premises/system-requirements) have the appropriate specifications.
 * Create a [PostgreSQL database](/docs/on-premises/database)
+* Setup a [Redis cache](/docs/on-premises/redis)
 * Ensure the [network](/docs/on-premises/network-configuration) is configured appropriately.
 * Ensure the [logs](/docs/on-premises/logging) are forwarded to a log aggregation service.
 * Make sure the [license file](/docs/on-premises/license) is mounted into the running containers.
@@ -38,4 +39,5 @@ Setup [database cleaning](/docs/on-premises/maintenance/database) to ensure opti
 
 :::warning this step is not optional
 Failure to enable database cleaning is likely to result in a gradual decline in system performance and, eventually, query timeouts and system failure.
-:::
+:::
+

website/docs/docs/on-premises/logging.md

@@ -4,11 +4,11 @@ title: Logging
 
 ## Output
 
-PactFlow application logs are sent to the standard output stream of the Docker container, with the expectation that the container orchestration service will collect and forward them to a log aggregation service.
+PactFlow application logs are sent to the standard output stream of the Docker container, with the expectation that the container orchestration service will collect and forward them to a log aggregation service. Both the UI and App logs will be interspersed here. They are distinguishable by the `application` property. UI will be `pactflow-ui` and API will be `pactflow-application`.
 
 ## Format
 
-The default log format is JSON. This can be changed by setting the [PACTFLOW_LOG_FORMAT](environment-variables#pactflow_log_format) environment variable.
+The log format is JSON.
 
 ## Level
 

website/docs/docs/on-premises/network-configuration.md

@@ -20,9 +20,8 @@ The host names of these services should also be whitelisted in the [PACTFLOW_WEB
 
 ## Certificate and TLS termination
 
-The recommended configuration is to terminate TLS at the load balancer, communicating over HTTP to the target application servers.
+The recommended configuration is to terminate TLS at the load balancer, communicating over HTTP to the target application servers, which in turn communicate over local sockets to applications within the container.
 
-If you would like to run PactFlow in a TLS-everywhere configuration there are several options:
+If you would like to run PactFlow in a TLS-everywhere configuration, modify the HAProxy configuration file (`/tmp/haproxy.cfg`) to bind a certificate to the `frontend`, and ensure the certificate has been appropriately mounted/added to the container.
 
-* Run the PactFlow container with a sidecar reverse proxy such as nginx configured with the TLS configuration of your choosing
-* Raise a feature request with us so that we can add it to our backlog, and support it natively with the underlying application server (Puma)
+Refer to the [HAProxy documentation](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/security/ssl-tls/client-side-encryption/) for further information.

website/docs/docs/on-premises/redis.md

@@ -0,0 +1,43 @@
+---
+title: Cache
+---
+
+## Introduction
+
+PactFlow requires a Redis Serialization Protocol (RESP)-compatible storage engine to support the following functions:
+
+- User session management
+- UI caching for improved performance
+
+## Session management
+
+User sessions are stored in Redis. Only a 128-bit session ID is shared with the user's browser. This ID is valid for 30 days and is signed with a server-side secret to prevent tampering—regardless of the cookie's expiry time. This protects against cookie replay attacks.
+
+All user data, including `idToken` and `accessToken`, is stored server-side and is never exposed to the user.
+
+## Caching
+
+To improve UI performance, PactFlow uses a server-side caching layer.
+
+This may result in temporary staleness—displayed content can differ based on when data was last fetched. Differences may appear between users or across browser sessions.
+
+PactFlow uses a *per-user* server-side cache, following a `stale-while-revalidate` strategy:
+
+- **Hot cache:** Data is used without validation.
+- **Warm cache:** Data is served immediately, and the cache is refreshed in the background.
+- **Cold cache:** The UI blocks until data is fetched from the API.
+
+This approach balances performance and freshness.
+
+When a user writes data through the UI, their *entire user cache* is invalidated immediately. This ensures correctness for the current user. However, if the change is made by another user or via the API, it may take longer to appear.
+
+As a fallback, the PactFlow UI follows HTTP cache-control conventions. If a user performs a hard refresh (`Shift+Refresh`), the browser sends headers like `Cache-Control: no-cache` or `Pragma: no-cache`, which bypass the cache.
+
+## Supported versions
+
+Engines that implement the [Redis Serialization Protocol (RESP) version 3](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md) are supported.
+
+Example implementations include:
+
+- Redis
+- Valkey

website/docs/docs/on-premises/releases/2.0.0.md

@@ -0,0 +1,43 @@
+---
+title: 2.0.0
+---
+
+## Release date
+
+27 June 2025
+
+## Introduction
+
+This major release introduces significant architectural changes and new features, including:
+
+1. A redesigned user interface.
+2. Migration to an Ubuntu Linux base image.
+3. Updated architecture using `HAProxy` for traffic routing and `supervisord` for process management.
+4. New caching and session management layers requiring a Redis Serialization Protocol (RESP)-compatible key/value storage engine.
+5. Many additional features, fixes, and improvements.
+
+For full details, including installation instructions, refer to the [2.x.x documentation](/docs/on-premises).
+
+## Features
+
+- **Major UI update**  
+  - Learn more about PactFlow's redesigned interface and improved navigation in the [UI migration guide](/docs/user-interface/migration/new).
+
+- **Bi-Directional Contract Testing**  
+  - A new [comparison engine](https://github.com/pactflow/openapi-pact-comparator/) delivers up to 100× faster performance than the [previous engine](https://github.com/pactflow/swagger-mock-validator/).
+  - Support added for [configurable behavior](/docs/bi-directional-contract-testing/contracts/oas/configuration.md).
+
+- **Stub server updates**  
+  - Now supports the Pact specification up to version 4.
+  - Includes additional [configuration options](/docs/stubs).
+
+## Migration notes
+
+Please review the following updates when migrating to version 2.0.0:
+
+1. A [Redis-compatible data store](/docs/on-premises/redis) is now required.
+2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. [More info](/docs/on-premises/environment-variables#pactflow_cookie_secret).
+3. The `PACTFLOW_LOG_FORMAT` environment variable is deprecated and has no effect. All logs are now output in JSON only.
+4. The base image has changed from Alpine Linux to Ubuntu 24.04. If you have customized the image, review your setup and update any installed tools or libraries accordingly.
+
+> **Note:** There are no breaking API or database changes in this release. All existing API calls, SDKs, and CLI integrations will continue to work as expected.