This document is useful in when getting an existing Perforce Helix Core installation to the optimal operating environment from any starting condition. Whether the starting environment is large enterprise or small, on-prem or cloud, or on any operating system, this guide can help get to the optimal deployment environment.

This document focuses on software rather than hardware aspects of an optimal operating environment. While hardware is not discussed in detail, the migration and upgrade plans describe in this document provide opportunity to test and change out hardware.

This document does not discuss case sensitivity, case-conversions, or Unicode changes.

This guide assumes some familiarity with Perforce Helix Core and does not duplicate basic information in the Helix Core documentation.

Please Give Us Feedback

Perforce welcomes feedback from our users. Please send any suggestions for improving this document or the SDP to

1. Introduction

1.1. Optimal Helix Core Operating Environment

Getting to an optimal operating environment for Perforce Helix Core first requires defining various aspects of optimal. For our purposes in this document, optimal means:

  • SDP version 2020.1+. This is the SDP version from which SDP upgrades are fully automated.

  • Helix Core (P4D) version 2019.1+. The P4D 2013.3 and 2019.1 versions were major architectural overhauls requiring special upgrade procedures.

  • P4D Server is operating on Linux, on a a major version with plenty of support life left in it. As of this writing, that would be RHEL/Rocky Linux 9, or Ubuntu 22.04. RHEL/Rocky Linux 8 and Ubuntu 20.04 are actively supported as well, but with less runway available. For EOL dates of various Linux distros, see:

  • Physical layer (server machines, storage subsystems, etc.) is as desired.

The above constitutes the desired End State a migration.

1.2. Motivation

This style of upgrade is commonly referred to as a global topology upgrade, sometimes part of a larger infrastructure modernization effort. Such upgrades are commonly driven by desires to maintain performance, security, supportability, access to new product features, and in some cases to escape custom aspects of local infrastructure.

If all defined aspects of the desired End State are already met, you don’t need this document. Instead, use the standard upgrade procedure documented in the Upgrades section of the SDP Guide.

In some cases, there is an additional motivation: to get assistance for managing Helix Core servers, or perhaps to get out of that role entirely (perhaps due to departure of key personnel). If there interest in turning over the keys to your Perforce Helix servers, consider the Helix Remote Administration program.

2. Migration Style Upgrades

This document focuses on the Migration-Style Upgrade strategy, as opposed to in situ (in place) upgrades. In situ upgrades are preferred when your deployment environment is already optimal, as defined above in Section 1.1, “Optimal Helix Core Operating Environment”. If all of the aspects are currently in the desired state, you don’t need this document. Instead, use the standard upgrade procedure documented in the Upgrades section of the SDP Guide.

If the hardware, operating system, or P4D/SDP versions are not as desired, this guide is for you. A Migration-Style Upgrade is great when you need to make a big change in the least disruptive way possible. A key characteristic is that of a Migration-Style Upgrade is that your original server environment is largely left alone, with little or no change.

2.1. Big Blue Green Cutovers

In a Migration-Style Upgrade, a new set of server machines and supporting infrastructure (such as storage) is deployed that reflect the desired End State. This set of servers is referred to as the "Green" servers or infrastructure. The current, live production equipment is referred to as the "Blue" servers or infrastructure.

In preparation for an eventual cutover, Helix Core data is brought into the Green environment. This is usually non-disruptive to users operating on the Blue (live production) environment.

The Green Environment operates for a time as a test environment, allowing opportunity to test various aspects of the new infrastructure before it become the production infrastructure. Depending on risks and needs, testing can be cursory or extensive, lasting days or months.

If your current method of operating Helix Core does not produce a regular backup of checkpoints and versioned files, a change to the Blue environment will be required to get at least some basic form of checkpoint process in place. This may involve disruptive operations that might need to be scheduled in a maintenance window before the Green environment can be setup initially.

2.2. Start State

The starting environment can pretty much anything:

  • Any P4D version going back to 1995.

  • P4D Server operating on Windows, UNIX, Mac, or Linux.

  • Any legacy method of managing Helix Core:

    • An older version of SDP (prior to 2020.1)

    • Home-grown custom scripts

    • Management scripts provided by a 3rd party such as ICManage.

    • p4dctl

    • entirely with manual procedures (including possibly no manual procedures).

2.3. End State

At a minimum, the desired End State of a Migration-Style Upgrade is as defined above in Section 1.1, “Optimal Helix Core Operating Environment”. In addition to those aspects, you may choose to add other aspects to your desired End State, depending on the goals of your migration. In the mindset of "While we’re at it," some common examples things added to the End State definition are:

Even if you are "pretty close" to the definition of optimal, say on Rocky Linux 8 but otherwise modern, the Migration-Style Upgrade is the preferred method of getting to the modern topology. (If your environment is optimal in all other respects and only the P4D version is older, than you might consider an in situ upgrade). Other options are not discussed in this document, because the Migration-Style Upgrade has significant benefits that often make it preferable even when other options are possible.

Your specific starting environment will have an impact on steps and procedures, as will be called out in this document.

Big changes can include:

  • Windows to Linux migration.

  • Upgrade of a major operating system version.

  • Upgrade of SDP from a version prior to 2020.1, where the SDP Legacy Upgrades applies, a well-documented but manual upgrade procedure. That document is for in situ upgrades of SDP — this document avoids the procedure entirely by using a Migration-Style Upgrade.

This primary scenario this document is focused on is a migration to a cloud provider, though only minor adaptations are needed if going to an on-premises environment. We lean toward a cloud environments for documentation purposes, because we can assume more, and define more, with a cloud as a target. If your target environment is on-prem some aspects are available.