# Perforce Helix Installer ## Welcome Welcome to the home of the Perforce Helix Installer project. The Helix Installer is the preferred method of installing Helix Core and the [Server Deployment Package (SDP)](https://swarm.workshop.perforce.com/projects/perforce-software-sdp). Perforce [Helix](http://www.perforce.com/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 gold baseline servers. 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 installation, Docker containers, etc. ## Safety WARNING 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. ## Support Status 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. ## Relationship to Server Deployment Package (SDP) The Helix Installer installs the [Server Deployment Package (SDP)](https://swarm.workshop.perforce.com/projects/perforce-software-sdp). By default, the Helix Installer installs a specific version of the SDP, using a simple tar file from the downloads folder of the SDP project. This version is coded in a Helix Installer script, which is updated and released from time to time following successful integration testing with the latest SDP version. The Helix Installer can also clone the SDP project's `dev` branch to get the latest software available in the given branch. This is done using Helix native DVCS features (e.g. `p4 clone`) to clone the SDP dev branch from the workshop, optionally overlaying the latest with a specified shelved changelist (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 specific (generally temporary) reason. ## Helix Installer Uses The installation is suitable for: * Test suites for Helix server trigger and broker filter scripts deployed in enterprise environments. For example, the [CBD](https://swarm.workshop.perforce.com/projects/perforce-software-cbd) test suite uses the Helix Installer to quickly spin up a test environment for server and triggers * Demonstrations of Helix Core * Proof of Concept (PoC) Deployments * Training * Evaluation and Pilot projects. Because the Helix Installer uses the SDP, you can **transition with minimal friction from a demo-grade installation to a production the Helix Installer to an enterprise-grade installation**. * **Bootstrapping production installation quickly**. * Testing SDP changes shelved to the dev branch in The Workshop (see SDP Dev Branch Testing below). Features --- * **Easy**. Provides reasonable defaults for port numbers, passwords, data storage areas, and all inputs that would otherwise require human interaction. * **Comprehensive**. Installs P4D and P4Broker, SDP, and a complete development pre-configured environment include Perl, P4Perl, Python, and P4Python, with appropriate shell environment settings to use them all immediately. And more to come -- future versions may include Helix Swarm, Jenkins, etc. * **Fast** - Runs in about 2 minutes with the `-fast` option, which omits the optional Perl and Python builds. * **Simplifies Enterprise Deployment**. While optimized for getting going quickly, the Helix Installer is designed to enable a fast path from a Proof of Concept (PoC) to small-scale production deployment following the Helix evaluation, with only a nominal hop from there to a large-scale global enterprise deployment. Global Enterprise deployments require additional planning and custom configuration based on the specific global topology. * Optionally pre-loads the [Perforce Sample Depot](http://answers.perforce.com/articles/KB/2439), making it instantly ready for training and evaluation purposes. ### Instructions and Usage Example #### Fast Demo Installations The `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 (acquired using Helix native DVCS features ala `p4 clone`). 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 -k -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](https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer/view/main/doc/reset_sdp.command_summary.txt) generated with `-man`: ``` ./reset_sdp.sh -man ``` 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. #### Configured Installation A configured installation can be done, allowing more options to be changed using [a generated `settings.cfg`](https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer/view/main/doc/settings.cfg) file. Do like so: ``` su - mkdir -p /hxdepots/reset cd /hxdepots/reset curl -k -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](https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer/view/main/doc/reset_sdp.command_summary.txt) generated with `-man`: ``` ./reset_sdp.sh -man ``` Edit the [generated `settings.cfg` file](https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer/view/main/doc/settings.cfg), 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 ``` Note: If you want to attempt local build and installation of Python/P4Python and Perl/P4Perl into `/p4/common/python` and `/p4/common/perl` areas, either drop the `-fast` flag, or run those separate installations afterward - see the description of the `-fast` flag in [the doc](https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer/view/main/doc/reset_sdp.command_summary.txt) for details on adding either or both of those afterward. #### Bootstrapping Production 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 `ext4`). In addition, acquire a license file from sales@perforce.com for evaluation or license purchase. See the **Volume Layout and Hardware** section of [the SDP Guide for Unix](https://swarm.workshop.perforce.com/projects/perforce-software-sdp/files/main/doc/SDP_Guide.Unix.docx) for more information. #### SDP Dev Branch Testing 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 -k -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. ## Helix Installer Release Notes See the [Helix Installer Release Notes](https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer/files/main/doc/ReleaseNotes.md). ## Helix Installer Roadmap ### Helix Installer 2021.1 The 2021.1 release is expected to add support for: * Add support for Helix Core r21.1 when it becomes available. * Add support for using SELinux in enforcing mode on CentOS 8. Note that SELinux in enforcing ode is supported currently on CentOS 7 as well as Ubuntu 18.04 and 20.04. ### Helix Installer 2020.2 Helix Installer 2020.2 is available today. It installs the following Helix Components, all fully configured an integrated: * **P4D** 2020.2 - the Helix Versioning Engine, the core of Helix (with or without SSL enabled). * **P4Broker** 2020.2 - the Helix Broker, enhances custom automation capabilities, simplifies maintenances. * **SDP** - Server Deployment Package (SDP), latest tarball release from the SDP mainline. * **Sample Depot** data set for training, evaluation, and demo, and pilot projects. The Helix Installer 2020.2 version handles all aspects of installation. It does the following: * Creates the `perforce` OS user, if needed. * Creates the home directory for the perforce user, if needed. * Adds OS packages as needed for P4Perl/P4Python local builds, for yum, apt, and zypper package management systems and repositories. Following installation, it also does the following to be more convenient for demos, and also give a more production-like feel: * Grants the `perforce` user sudo access. * Creates default `~perforce/.bash_profile` and `.bashrc` files (if they do not already exist). * Connects to the [Perforce Package Repository](https://www.perforce.com/perforce-packages) (APT and YUM only) to enable [Helix Swarm](https://www.perforce.com/products/helix-swarm) installation. (Note this script acquires `p4d` and other binaries directly from the Perforce FTP server). * Makes firewall adjustments (`firewalld` type firewalls only). * Makes init system adjustment, for both SysV and systemd init mechanisms. ## Test Suite The Helix Installer Test Suite uses [Vagrant](https://www.vagrantup.com), a command-line virtualization interface and [Virtual Box](https://www.virtualbox.org) virtualization technology. The test suite can be used for standalone demonstrations of the Helix Installer or the SDP. ## Platform Support Helix Installer 2019.4 Platform Support notes: Distro | Support | Notes --- | --- | --- Amazon Linux 2| M | Supported. CentOS/RHEL 6.8+ | U | Unsupported due to EOL for this OS. (Still works as of Helix Installer 2020.2). CentOS/RHEL 7.8+ | A | Supported. CentOS/RHEL 8 | A | Supported. SuSE 12 | L | Known to work at least once, no ongoing testing at present. Ubuntu 16.04 LTS Release (Xenial)| U | Unsupported. Ubuntu 18.04 LTS Release (Bionic)| L| The default shell in bionic causes the Helix Installer to fail. OSX 10.14 Mojave | L | Limited support for Mac OSX/Darwin. Does not create 'perforce' OS user, other limitations. ### Support Codes: * **A**: Included in the automated test suite; should work reliably. * **M**: Occasional manual testing done in this environment. * **L**: Very limited support. * **U**: Unsupported ## Project Status As of December 2020 this project is functional and active, and has been actively used since April 2015. It has been actively maintained to keep pace with SDP changes up to and including the SDP 2020.1 release. ## Case Studies ### Case Study: Sample Usage of Helix Installer in CBD Test Suite The [Component Based Development (CBD)](https://swarm.workshop.perforce.com/projects/perforce-software-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](https://swarm.workshop.perforce.com/projects/perforce-software-cbd/files/main/test/auto_test_cbd_vagrant.sh) 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. ### Case Study: Sample Usage of Helix Installer in Battle School Workshop A slightly modified Helix Installer is a key component of the Battle School Workshop. 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. ## Contact Us Please [contact Perforce Consulting Services] (mailto:consulting@perforce.com) for more information.