docs: 2.x migration guide #420
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| title: Migrating from 1.x | ||
| --- | ||
|
|
||
| This major release introduces significant architectural changes and new features: | ||
|
|
||
| 1. A redesigned user interface | ||
|
There was a problem hiding this comment. Let's change it to: "A redesigned user interface. Learn more about it in the UI migration guide." |
||
| - Learn more about the new interface and navigation in the [UI migration guide](/docs/user-interface/migration/new). | ||
| 2. A switch to an Ubuntu Linux base image (from Alpine) for improved compatibility and security posture. | ||
| 3. Internal architecture updates, including the use of `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. | ||
|
|
||
| ## Migration notes | ||
|
|
||
| The 2.x release line is almost entirely backwards compatible with 1.x. Only the following changes are required to install and run it: | ||
|
There was a problem hiding this comment. Let's change it to: "The 2.x release line remains largely compatible with 1.x. To install and run it, you must make the following changes:" |
||
|
|
||
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) (such as Redis or Valkey) is now required. | ||
|
There was a problem hiding this comment. You must use a Redis-compatible data store (such as Redis or Valkey). Ensure you set the |
||
| - Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
|
There was a problem hiding this comment. Delete, as it's in the point above. |
||
| 2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. See [documentation](/docs/on-premises-2x/environment-variables#pactflow_cookie_secret) for details. | ||
|
There was a problem hiding this comment. Let's change it to: "Set the |
||
| 3. The `PACTFLOW_LOG_FORMAT` environment variable is deprecated and has no effect. All logs are now output in JSON only. | ||
|
There was a problem hiding this comment. Let's change it to: "Do not use the |
||
| 4. The base image has changed from Alpine Linux to Ubuntu 24.04. If you customized the image, review and update your setup, including any additional tools or libraries. | ||
|
There was a problem hiding this comment. Let's change it a bit: "We changed the base image from Alpine Linux to Ubuntu 24.04. If you customized the image, review your setup and update any installed tools or libraries accordingly." |
||
|
|
||
| > **Note**: This release does not include any database or data migrations. You can freely upgrade or roll back between 1.x and 2.x without concerns about database compatibility. All existing API calls, SDKs, and CLI integrations continue to work as expected. | ||
|
There was a problem hiding this comment. Let's change it to: "This release does not require any database or data migrations. You can upgrade or roll back between 1.x and 2.x without database compatibility issues. All existing API calls, SDKs, and CLI integrations continue to work." |
||
| ## Migration Checklist | ||
|
|
||
| Use this checklist to prepare for upgrading from PactFlow 1.x to 2.x. | ||
|
There was a problem hiding this comment. Let's change it to: "Use the following checklist to prepare for the upgrade from PactFlow 1.x to 2.x." |
||
|
|
||
| ✅ **Redis requirement** | ||
| - [ ] Provision a [Redis-compatible data store](/docs/on-premises-2x/redis) (Redis or Valkey). | ||
| - [ ] Set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
|
|
||
| ✅ **Cookie secret length** | ||
| - [ ] Ensure `PACTFLOW_COOKIE_SECRET` is **at least 64 characters**. | ||
| - [ ] Update your environment configuration if required. | ||
|
|
||
| ✅ **Logging format** | ||
| - [ ] Remove any usage of the `PACTFLOW_LOG_FORMAT` environment variable. | ||
| - [ ] Update monitoring/forwarding pipelines to expect **JSON logs only**. | ||
|
There was a problem hiding this comment. Let's change it to: "Update monitoring and forwarding pipelines to expect JSON logs only." |
||
|
|
||
| ✅ **Base image** | ||
| - [ ] Note that the base image has changed from Alpine Linux to **Ubuntu 24.04**. | ||
| - [ ] If you maintain a custom image, review and update any tools, libraries, or scripts. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -35,9 +35,10 @@ For full details, including installation instructions, refer to the [2.x.x docum | |
|
|
||
| Please review the following updates when migrating to version 2.0.0: | ||
|
|
||
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) is now required | ||
|
There was a problem hiding this comment. Let's change it to: "You must use a Redis-compatible data store (such as Redis or Valkey). Ensure you set the REDIS_URL environment variable." |
||
| 1. Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
|
There was a problem hiding this comment. Delete, as it's in the point above. |
||
| 2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. [More info](/docs/on-premises-2x/environment-variables#pactflow_cookie_secret). | ||
|
There was a problem hiding this comment. Let's change it to: ""Set the PACTFLOW_COOKIE_SECRET environment variable to a value that is at least 64 characters. Read more in Environment Variables." |
||
| 3. The `PACTFLOW_LOG_FORMAT` environment variable is deprecated and has no effect. All logs are now output in JSON only. | ||
|
There was a problem hiding this comment. Let's change it to: "Do not use the PACTFLOW_LOG_FORMAT environment variable. It is deprecated and has no effect. All logs now output in JSON format 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. | ||
|
There was a problem hiding this comment. Let's change it to: "We changed the base image from Alpine Linux to Ubuntu 24.04. If you 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. | ||
|
There was a problem hiding this comment. Let's change it to: "There are no breaking API or database changes in this release. All existing API calls, SDKs, and CLI integrations continue to work." |
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's change it to:
"This release includes major architectural updates and introduces new features, such as:"