docs: 2.x migration guide #420
Conversation
✅ Deploy Preview for docs-pactflow-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
mefellows
force-pushed
the
docs/PACT-4693-on-prem-2x-migration-guide
branch
from
5f91ef8 to
b24b46f
Compare
| title: Migrating from 1.x | ||
| --- | ||
|
|
||
| This major release introduces significant architectural changes and new features: |
There was a problem hiding this comment.
Let's change it to:
"This release includes major architectural updates and introduces new features, such as:"
|
|
||
| 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."
|
|
||
| ## 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:"
|
|
||
| The 2.x release line is almost entirely backwards compatible with 1.x. Only the following changes are required to install and run it: | ||
|
|
||
| 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 REDIS_URL environment variable.
| The 2.x release line is almost entirely backwards compatible with 1.x. Only the following changes are required to install and run it: | ||
|
|
||
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) (such as Redis or Valkey) is now required. | ||
| - 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.
|
|
||
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) (such as Redis or Valkey) is now required. | ||
| - Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
| 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 PACTFLOW_COOKIE_SECRET environment variable to a value that is at least 64 characters. Read more in Environment Variables."
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) (such as Redis or Valkey) is now required. | ||
| - Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
| 2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. See [documentation](/docs/on-premises-2x/environment-variables#pactflow_cookie_secret) for details. | ||
| 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."
| - Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
| 2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. See [documentation](/docs/on-premises-2x/environment-variables#pactflow_cookie_secret) for details. | ||
| 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 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."
| 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 customized the image, review and update your setup, including any additional tools or libraries. | ||
|
|
||
| > **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."
|
|
||
| ✅ **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."
| --- | ||
|
|
||
| :::warning | ||
| The 1.x line of PactFlow On-Prem is now in maintenance mode and will only receive security updates. It will reach end of life on March 11, 2026, after which it will no longer be supported. |
There was a problem hiding this comment.
Let's change it to:
"PactFlow On-Prem 1.x is now in maintenance mode and receives security updates only. It will no longer be supported after March 11, 2026."
| :::warning | ||
| The 1.x line of PactFlow On-Prem is now in maintenance mode and will only receive security updates. It will reach end of life on March 11, 2026, after which it will no longer be supported. | ||
|
|
||
| To ensure you have access to the latest features and improvements, please upgrade to 2.x as soon as possible. |
There was a problem hiding this comment.
Let's change it to:
"To benefit from the latest features and improvements, upgrade to version 2.x as soon as possible."
| 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. | ||
| 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. A [Redis-compatible data store](/docs/on-premises-2x/redis) is now required. | ||
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) is now required | ||
| 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.
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) is now required. | ||
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) is now required | ||
| 1. Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
| 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."
| 1. A [Redis-compatible data store](/docs/on-premises-2x/redis) is now required | ||
| 1. Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
| 2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. [More info](/docs/on-premises-2x/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. |
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."
| 1. Ensure you set the [`REDIS_URL`](/docs/on-premises-2x/environment-variables#redis_url) environment variable. | ||
| 2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. [More info](/docs/on-premises-2x/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. |
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."
| 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. | ||
| > **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."
2 participants
No description provided.