Welcome to the home of the Perforce Helix Installer project. The Helix Installer is an advanced method for installing Helix Core and the Server Deployment Package (SDP).
IT SHOULD ONLY BE USED IN A TOTALLY NEW HELIX CORE INSTALLATION!! IF IN DOUBT DONT USE IT.
DO NOT USE THIS TOOL IF YOU HAVE EXISTING DATA IN YOUR HELIX REPOSITORY!! YOU RISK DELETING EVERYTHING!!
Do not use this tool to upgrade the SDP OR P4D!!
Perforce Helix is a unified platform for collaborative development, version management, and protection of intellectual property. It consists of an integrated ecosystem of proven, enterprise-grade systems for versioning, collaboration and code review, continuous integration and delivery, and other aspects of a DevOps pipeline.
This Helix Installer is capable of quickly transforming a vanilla Linux machine into a production-grade deployment of Helix Core. It also helps standardize deployment of a fleet of Helix Core servers across an enterprise-scale deployment of Helix Core.
For public cloud usage, the Helix Installer provides a way to build "Golden Copy" baseline server installations. For example, it plays a role in building Amazon Machine Images (AMIs). It is useful in other Linux installations, including public/private clouds, on-prem virtual or bare metal hardware Docker containers, etc. See Public Cloud Usage below.
Note that this software SHOULD NEVER EXIST on a Production Perforce server. The is intended to quickly tear down and rebuild a fresh Perforce server (e.g. for operating test suites). It should not exist on a machine containing real Perforce data.
It is useful for doing an initial installation, e.g. to bootstrap a production machine with the SDP structure. After a successful install, the core
reset_sdp.sh script is moved aside to reset_sdp.sh.txt and the execute bit is removed. The script should be removed entirely before going live in production.
As of February, 2023:
This software is community supported. Evolution can also be driven by engaging Perforce Consulting. Please DO NOT contact Perforce Support for the Helix Installer, as it is not an officially supported product offering.
While not officially supported, the Helix Installer is actively maintained and absolutely integral to many processes that build upon the Helix Installer for higher levels of automation for various purposes such as full deployment automation of Helix Core servers. The code is exercised frequently and is relied on. Contact Perforce Consulting for more information.
The Helix Installer is installs the Server Deployment Package (SDP).
By default, the Helix Installer installs the latest mainline version of the SDP acquired from The Workshop over the public internet. It acquires the latest patch of the Helix Core binaries (currently Helix Core 2020.2) available from the Perforce FTP server.
This section is for advanced usage specific to developing the SDP and Helix Installer.
The Helix Installer can also clone the SDP project's
dev branch to get the very latest, but possibly not yet fully tested, software available in the SDP
dev branch. This is done using Helix native DVCS features (e.g.
p4 clone) to clone the SDP dev branch from The Workshop. Optionally a specified shelved changelist can unshelved over the dev branch (see SDP Dev Branch Testing below). As a general rule, it is best to stick with the default 'main' branch unless Perforce Consulting recommends using the dev branch for some reason (with any such reason being temporary and customer-specific).
The installation is suitable for:
-fastoption, which omits the optional package installation.
reset_sdp.sh script is the only script that should be downloaded. It downloads everything it needs, including other scripts and files from this Helix Installer package, executables from the Perforce FTP site, and the SDP from The Workshop (the web front end to the Public Depot).
Once creating a fresh vanilla server machine for a supported platform, do this as the root user:
mkdir -p /hxdepots/reset cd /hxdepots/reset curl -L -s -O https://swarm.workshop.perforce.com/downloads/guest/perforce_software/helix-installer/main/src/reset_sdp.sh chmod +x reset_sdp.sh
Read the documentation the manual page generated with
And then, the big moment. Make it happen:
./reset_sdp.sh -fast 2>&1 | tee reset_sdp.log
A similar procedure works for Mac OSX, except that the standard Mac interface is used manually for creating the
perforce user account.
A configured installation can be done, allowing more options to be changed using a generated
settings.cfg file. Do like so:
su - mkdir -p /hxdepots/reset cd /hxdepots/reset curl -L -s -O https://swarm.workshop.perforce.com/download/guest/perforce_software/helix-installer/main/src/reset_sdp.sh chmod +x reset_sdp.sh
Generate a default config file:
./reset_sdp.sh -C > settings.cfg
Read the documentation the manual page generated with
Edit the generated
settings.cfg file, changing the values as desired. And then run using that generated file:
./reset_sdp.sh -c settings.cfg -fast 2>&1 | tee log.reset_sdp.txt
The Configured Installation method described above is the best way to bootstrap a production installation. If used for this purpose, and if separate storage mounts are to be used for optimal and/or at-scale installations, these mounts should be configured (e.g. AWS CloudFormation Templates, or Terraform) first:
/hxdepots- Used for versioned files and checkpoints, etc.
/hxmetadata- Used for live and offline databases, etc.
/hxlogs- Used for script and application logs, active journal, etc.
These should all be configured as
xfs filesystems (or alternately
In addition, acquire a license file from email@example.com for evaluation or license purchase.
See the Volume Layout and Hardware section of the SDP Guide for Unix for more information.
The Helix Installer can be used to test SDP changes shelved to the SDP dev branch in The Workshop. The following example illustrates testing a change in shelved changelist 23123:
su - mkdir -p /hxdepots/reset cd /hxdepots/reset curl -L -s -O https://swarm.workshop.perforce.com/downloads/guest/perforce_software/helix-installer/main/src/reset_sdp.sh chmod +x reset_sdp.sh ./reset_sdp.sh -b dev,@23123 2>&1 | tee reset_sdp.CL23123.log
After the first test, an iterative test cycle may follow on the same shelved changelist. For each test iteration, the shelved changelist is first updated in the workspace from which the change was originally shelved, e.g. with a command like
p4 shelve -f -c 23123.
Then a new test can be done by calling
reset_sdp.sh with the same arguments. The script will re-install the SDP cleanly, and then re-apply the updated shelved changelist.
See the Helix Installer Release Notes.
Helix Installer 2023.1 is available today. It installs the following Helix Components, all fully configured an integrated:
The Helix Installer 2023.1 version handles all aspects of installation. It does the following:
perforceOS user, if needed.
Following installation, it also does the following to be more convenient for demos, and also give a more production-like feel:
perforceuser sudo access (optionally limited sudo access).
.bashrcfiles (if they do not already exist).
p4dand other binaries directly from the Perforce FTP server).
firewalldtype firewalls only).
The Helix Installer Test Suite uses Docker virtualization technology. The test suite can be used for standalone demonstrations of the Helix Installer or the SDP.
Helix Installer 2023.1 Platform Support notes:
|Amazon Linux 2||L||Limited support.|
|Rocky Linux 8.5+||A||Supported. Also supported: Rocky Linux 8 Security Hardened by Perforce OpenLogic.|
|Ubuntu 20.04 LTS Release (Focal Fossa)||A||Supported|
|Ubuntu 22.04 LTS Release (Jammy Jellyfish)||A||Supported|
|CentOS/RHEL 8.x||L||Supported, but end of life.|
|Ubuntu 18.04 LTS Release (Bionic Beaver)||L||The default shell in Bionic causes the Helix Installer to fail.|
|Ubuntu 16.04 LTS Release (Xenial)||U||Unsupported.|
|OSX 10.14 Mojave||L||Limited support for Mac OSX/Darwin. Does not create 'perforce' OS user, other limitations. Note: There is no plan to support newer versions OSX due to lack of need and OS changes.|
|SuSE 15||L||Known to work at least once, no ongoing testing.|
|SuSE 12||L||Known to work at least once, no ongoing testing.|
|CentOS/RHEL 6.9||U||Unsupported, but known to work.|
As of February 2023 this project is functional and active, and has been actively used since its inception in April 2015. It has been actively maintained to keep pace with SDP changes up to and including the SDP 2023.1 release.
For building out cloud environments, some customers build "Golden Copy" images based on the Helix Installer.
AWS CloudFormation templates as well as cloud-agnostic Terraform and similar technologies can be used to build baseline infrastructure in any cloud, private or public. Then the Helix Installer transforms a baseline machine (configured with the 3
/hx* storage volumes) into a baseline Helix machine to be a master, edge server, etc. Then after data is loaded, a new "local baseline" machine image with local Helix data, potentially Terabytes, can be added.
To further simplify this, publicly available Amazon Machine Images (AMIs) based on this Helix Installer are available in AWS and Azure marketplaces. For more information, see the Perforce Enhanced Studio Pack.
While using the latest publicly available versions of software is generally reliable and common practice, there are usage scenario where guaranteed reliability is required, and/or public public internet access is not available. For these scenarios, the Helix installer sports a
-local option for Local Mode installation.
For a guaranteed reliable install that does not rely on public internet access, the Helix Installer also supports installation with fixed (and possibly older) versions of the software it needs, specifically:
To prepare for stable installation, a local tarball must first be created in an environment that has public internet access. This is done like so:
root, download the SDP tarball.
mkdir -p /hxdepots/downloads cd /hxdepots/downloads curl -L -s -o sdp.Unix.tgz https://swarm.workshop.perforce.com/downloads/guest/perforce_software/sdp/downloads/sdp.Unix.tgz?v=%2346 cd .. tar -xzf downloads/sdp.Unix.tgz
The odd-looking text at the end if the URL starting with
?v=%23 is a version specifier (not a typo).
Execute commands like these samples to get the binaries. This gets Helix Core 2023.1 binaries. Tweak the URL as desired. For example, change r23.1 to r22.2 in the examples below to get the 2022.1 binaries.
cd /hxdepots/sdp/helix_binaries curl -s -O http://ftp.perforce.com/perforce/r23.1/bin.linux26x86_64/p4 curl -s -O http://ftp.perforce.com/perforce/r23.1/bin.linux26x86_64/p4d curl -s -O http://ftp.perforce.com/perforce/r23.1/bin.linux26x86_64/p4broker curl -s -O http://ftp.perforce.com/perforce/r23.1/bin.linux26x86_64/p4p chmod +x p4*
Only the latest patch for a specified major version (e.g. r23.1) can be obtained from the Perforce FTP server. There is no standard way to get an earlier patch, as new patches supersede older ones.
Then, get the tarball for the Helix Installer (2023.1) onto the machine in which you intend to perform the stable installation.
cd /hxdepots/downloads curl -L -s -o helix_installer.tgz https://swarm.workshop.perforce.com/downloads/guest/perforce_software/helix-installer/downloads/helix_installer.tgz?v=%2318 tar -xzf helix_installer.tgz rm -rf /hxdepots/reset cp -pr hi/src ../reset
The odd-looking text at the end if the URL starting with
?v=%23 is a version specifier (not a typo).
Acquire the Sample Depot training data set from the Perforce FTP server. This can be skipped if you plan to use the
-no_sd (No Sample Depot) option to the Helix Installer.
cd /hxdepots/downloads curl -s -O http://ftp.perforce.com/perforce/tools/sampledepot.tar.gz
With the steps above completed to prepare local data, the entire /hxdepots tree, including the Helix Installer, SDP, Helix binaries, and optional Sample Depot.
cd / tar -czf hxdepots.tgz hxdepots
hxdepots.tgz tarball can then be transferred (over air gap network if necessary) to the machine on which stable installation is to be performed. On that machine, extract such that the structure contains:
The precise commands to transfer files and untar on the other machine will vary depending on whether mount points are involved, what directories may already exist on the target machine, and your file transfer mechanism. One of the commands need will be
tar -xzf hxdepots.tgz to create the folder structure that must end up in
/hxdepots. It may be necessary to copy that to some other temporary location first and use rsync or similar to populate
When done, you can execute the Helix Installer per usual instructions above, except that you will use the
-local option, and and avoid using
-B (blast) option, as that will require rebuilding the
/hxdepots structure on the air gapped machine.
In late 2021, a Perforce Consulting customer embarked on a project to automate deployment of a new Helix Core edge or replica server to such a degree that someone with limited knowledge of Perforce Helix could deploy a new server in an enterprise, with only minimal inputs.
A pre-requisite was a baseline VM image built with just the basics:
perforceOS user with limited sudo.
For ease of use, the user interface chosen was simply the existing and familiar
mkrep.sh script in the SDP, which already captures the information needed:
mkrep.sh enables custom post-processing programs to be called with hooks. The hooks are used so
mkrep.sh post-processing picks up where
mkrep.sh leaves off, doing everything that
mkrep.sh doesn't, including:
rotate_journal.shto get replica metadata configuration into a numbered journal file.
load_checkpoint.shto load the latest checkpoint and subsequent journals on the new machine.
p4verify.shscript to schedule all archives for transfer.
The implementation uses the "Tight Ship" features of the Helix Management System (HMS) to store key data bits enabling operation behind a restrictive corporate firewall, such as
settings.cfgfile for the Helix Installer with local preferences for mount points, etc.
Some enterprise customers take full advantage of the Helix Installer for public cloud and hybrid environments that blend public cloud, private cloud, and on-prem systems. The Helix Installer integrates into a larger technology stack to build out sophisticated global topologies. The key build blocks are the Helix Installer (
reset_sdp.sh) and the SDP
mkrep.sh, which together can easily build out a sophisticated global Helix Core topology in minutes -- longer of course when you add in Terabytes of data. At the top of that food chain, the Helix Management System (HMS) adds a layer of global topology awareness.
A slightly modified Helix Installer is an integral component of the Lab Engine behind the Battle School Workshop training course. The Battle School Workshop Lab Engine quickly tears down and spins up a fresh, enterprise-style Helix installation -- and then breaks it in order to simulate real-world problems that students learn to identify and fix. The Battle School version of the Helix Installer (not available for public consumption) adds a simulated global topology with replicas and edge servers.
Note: This is an older example, as there is no longer a need for custom automation to support CBD workflows in Helix Core; this example was developed circa 2013.
The Component Based Development (CBD) system, another project in The Workshop, uses this Helix Installer as part of its automated test suite. In conjunction with Vagrant and Virtual Box, which build a vanilla VM from the ground up, the CBD Test Suite uses the Helix Installer to deploy a Perforce server, complete with Sample Depot test data set, plus Python and P4Python needed to test the CBD scripts.
Please [contact Perforce Consulting Services] (mailto:firstname.lastname@example.org) for more information.