Deploying and installing Helix Artifacts

This section describes the deployment and installation process for the Helix Artifacts micro-services.

Prerequisites

The Helix Artifacts micro-services are a wrapped JAR that runs as a Windows or Linux service. It uses a config.properties file for each micro-service to store the configuration details and connection information for the services, the Helix server, and the Elasticsearch instance.

Dependencies

Helix Artifacts has the following dependencies:

  • The micro-services must all have access to the common cache

  • The micro-services must have REST access to each other

  • The micro-services must have a Java 11 JRE

  • The ha-web micro-service runs in ha-core's JVM as a sidecar service

  • Helix Artifacts must have a deployment of the Helix Search and ElasticSearch 7.x

External services

Helix Artifacts requires the following external services:

  • Helix server 2020.1 or later (latest patch of server version required): a new instance of Helix server or an existing Edge or Replica server

    • Perforce Service User: A Standard or Service user with admin or super access. Used to authorize the proxy connections. Must be a Service user at security level 5 and above. At security level 4 and below, this can be the same user as the Perforce Admin user. For instructions on creating the Perforce Service User and printing out the ticket, see Creating the Perforce Service User

      Important
      • If a Service user is used, the long lived ticket must be a local ticket and not an all hosts ticket.

      • Security level 6 requires the Helix server to have a valid server spec with the AllowedAddresses field set. For information about Security level 6, see Server security levels in the Helix Core Server Administrator Guide.

    • Perforce Admin User: A Standard user with a minimum of admin access, used for keys. For instructions on creating the Perforce Admin User and printing out the ticket, see Creating the Perforce Admin User .

      Tip

      A Perforce Admin User or Perforce Service User with super permissions is required if you want to use user-generated keys. These keys are accessed from the Keys view, see Viewing keys. Alternatively, the default behavior is to use the anonymous user, and then users can use their own keys.

    • Optional: Anonymous User: An Anonymous user with read permissions for the areas of the depot you want to allow search result access to. The anonymous search user is used for the unsupported search web pages. For instructions on setting the Anonymous User and printing out the ticket, see Creating the anonymous user (optional). If the anonymous user is not defined, anonymous access is disabled.

  • Helix Search 2021.2 or later. For installation and configuration, see the Helix Core Search Developer Guide.

  • ElasticSearch 7.8.1 to 7.17.0: For installation and configuration, see the Helix Core Search Developer Guide.

    • Permission filter builds supplied for 7.8.1 to 7.17.0

Installer layout

The directory layout after installation depends on the operating system but is typically located under:

  • Linux: /opt/perforce/helix-artifacts/...

  • Windows: c:\Program Files\Perforce\helix-artifacts\...

- LICENSE.txt                                     (EULA and attributions)
- cache/                                          (default shared cache in installer's root))
- jre/                                            (Java RunTime)
- ha-core/
   - ha-core-fat.jar                              (ha-core JAR)
   - ha-core.vmoptions                            (wrapper JVM options)
   - ha-core                                      (service wrapper)
   - log4j2.xml                                   (standard log configuration file) 
   - config.properties                            (configuration information for the service)
   - tmp/                                         (temporary file directory)
   - log/
      - error.log                                 (service wrapper error log)
      - ha-core.log                               (ha-core service log)
- ha-XXX/
   -   ... (the same files as ha-core)

Creating the users required by the external services

You must create the Helix server users and tickets required by the external services.

Creating the Perforce Service User

The Perforce Service User with a minimum of admin permissions. Used to authorize the proxy connections. Must be a Service user at security level 5 and above.

The Perforce Service user name and ticket details are required when you set the following configurables:

  • com.perforce.artifacts.core.service.p4user

  • com.perforce.artifacts.core.service.p4ticket

Creating the Perforce Admin User

Tip

A Perforce Admin User or Perforce Service User with super permissions is required if you want to use user-generated keys. These keys are accessed from the Keys view, see Viewing keys. Alternatively, the default behavior is to use the anonymous user, and then users can use their own keys.

The Perforce Admin User needs a minimum of admin permissions for keys.

The Perforce Admin User user name and ticket details are required when you set the following configurables:

  • com.perforce.artifacts.core.admin.p4user

  • com.perforce.artifacts.core.admin.p4ticket

Creating the anonymous user (optional)

The Anonymous user needs read permissions for the areas of the depot you want to allow search result access to.

The anonymous user name and ticket details are required when you set the following configurables:

  • com.perforce.artifacts.xxxxx.anonymous.p4user

  • com.perforce.artifacts.xxxxx.anonymous.p4ticket

  • Where xxxxx is the name of the repository micro-service.

Installing Helix Artifacts for Windows

To install the Helix Artifacts and the protocol services:

  1. Check that you have met the dependencies and external service requirements before starting the installation, see Prerequisites.

  2. Download the Helix Artifacts installer from the Helix Artifacts download page on the Perforce website.

  3. Double click on the installer to start it, confirm that you want the installer to make changes to your computer when prompted, and accept the license agreement.

  4. Image of the Set the destination directory for the installation dialog

  5. Select the installation directory and click Next >.

  6. Image of the Select the services to install dialog

  7. Select the components for the protocols you want to install and click Next >.

  8. Image of the Configure the ha-core service dialog

  9. Configure the Helix Artifacts service and click Next >.

  10. Image of the Configure the Helix Core connection dialog

  11. Configure the connection to the Helix server:

    Click Next >.

  12. Image of the Complete the installation of Helix Artifacts dialog

  13. To complete the installation click Finish.

  14. To configure Helix Artifacts do one of the following:

    • Open the configuration web page using the connection details you set for the Helix Artifacts during the installation.

    • Edit the config.properties file for ha-core in the installation directory.

Installing Helix Artifacts for Linux

Debian and RPM packages are available for Helix Artifacts:

  1. Check that you have met the dependencies and external service requirements before starting the installation, see Prerequisites.
  2. Configure the Perforce package repository, on the server hosting the Helix Artifacts micro-services.

    As root, follow the instructions for your OS distribution:

  3. Import the Perforce package signing key, on the server hosting Helix Search.

    Follow the instructions for your OS distribution:

    For information about how to verify the authenticity of the signing key, see: https://www.perforce.com/perforce-packages

  4. Install the Helix Artifacts package on the server hosting Helix Artifacts.

    Follow the instructions for your OS distribution:

  5. Restart the Helix Artifacts service:
  6. Follow the instructions for your OS distribution:

  7. Check that everything is green by navigating to:
  8. http://myhelixartifacts.mydomain.com:1600/settings/status

  9. To configure Helix Search do one of the following:
    • Open the configuration web page using the connection details you set for the Helix Artifacts service during the installation.
    • Edit the config.properties file for ha-core in the installation directory.

Deploying Helix Artifacts with Docker

Important

ha-core is the core service and is required by all of the other services.

The Helix Artifacts micro-services are available as docker images on the Perforce Docker Hub.

Use one of the following methods to deploy Helix Artifacts:

Deploying Helix Artifacts using Docker containers

  1. Install Docker on the machine that will host Helix Artifacts

  2. Check that you have met the dependencies and external service requirements before starting the installation, see Prerequisites.

  3. Pull the images from the Perforce Docker Hub with:

  4. docker pull perforce/ha-core:latest

    docker pull perforce/ha-maven:latest

    docker pull perforce/ha-docker:latest

    docker pull perforce/ha-generic:latest

    docker pull perforce/ha-pypi:latest

    docker pull perforce/ha-nuget:latest

  5. The Helix Artifacts Docker image has a default configuration which must be edited to suit your deployment. When you have edited your config.properties files, copy your configuration to a host directory.

    For sample configuration files, see Micro-service configuration files.

  6. Bind mount your config.properties file and start the container with:

  7. docker run -d -it --name <yourcontainername> --mount type=bind,source=<absolute_location_of_config.properties>,target=/data/config.properties perforce/ha-core:latest

    For example:

    docker run -d -it --name testcore --mount type=bind,source="$(pwd)"/ha-core/config.properties,target=/data/config.properties perforce/ha-core:latest

Deploying Helix Artifacts using Docker compose

Docker compose builds the images and starts all of the containers.

  1. Install Docker on the machine that will host Helix Artifacts

  2. Check that you have met the dependencies and external service requirements before starting the installation, see Prerequisites.

  3. The Helix Artifacts Docker image has a default configuration which must be edited to suit your deployment. When you have edited your config.properties files, copy your configuration to a host directory.

    For sample configuration files, see Micro-service configuration files.

  4. Copy the config.properties files for all of the services to $pwd/<service_name>/

  5. The <service_name> can be ha-core, ha-maven, ha-docker, ha-generic, ha-pypi, ha-nuget.

  6. Build the containers (ha-core, ha-maven, ha-docker, ha-generic, ha-pypi, and ha-nuget) with:

  7. docker-compose build

  8. Start the containers with:

  9. docker-compose up

    For more information, see the content of the docker-compose.yml file below.

Docker compose YAML file

version: '3.3'
 
services:
 
  ha-core.helix:
    image: perforce/ha-core:latest
    hostname: ha-core
    domainname: helix
    ports:
      - 1600:1600
    volumes:
      - ./volumes/cache:/cache
      - type: bind
        source: $PWD/ha-core/files/config.properties
        target: /data/config.properties
    tty: true
 
  ha-generic.helix:
    image: perforce/ha-generic:latest
    hostname: ha-generic
    domainname: helix
    ports:
      - 1602:1602
    depends_on:
      - ha-core.helix
    volumes:
      - ./volumes/cache:/cache
      - type: bind
        source: $PWD/ha-generic/files/config.properties
        target: /data/config.properties
    tty: true
 
  ha-maven.helix:
    image: perforce/ha-maven:latest
    hostname: ha-maven
    domainname: helix
    ports:
      - 1603:1603
    depends_on:
      - ha-core.helix
    volumes:
      - ./volumes/cache:/cache
      - type: bind
        source: $PWD/ha-maven/files/config.properties
        target: /data/config.properties
    tty: true
 
  ha-nuget.helix:
    image: perforce/ha-nuget:latest
    hostname: ha-nuget
    domainname: helix
    ports:
      - 1604:1604
    depends_on:
      - ha-core.helix
    volumes:
      - ./volumes/cache:/cache
      - type: bind
        source: $PWD/ha-nuget/files/config.properties
        target: /data/config.properties
    tty: true

  ha-docker.helix:
    image: perforce/ha-docker:latest
    hostname: ha-docker
    domainname: helix
    ports:
      - 1605:1605
    depends_on:
      - ha-core.helix
    volumes:
      - ./volumes/cache:/cache
      - type: bind
        source: $PWD/ha-docker/files/config.properties
        target: /data/config.properties
    tty: true

  ha-pypi.helix:
    image: perforce/ha-pypi:latest
    hostname: ha-pypi
    domainname: helix
    ports:
      - 1606:1606
    depends_on:
      - ha-core.helix
    volumes:
      - ./volumes/cache:/cache
      - type: bind
        source: $PWD/ha-pypi/files/config.properties
        target: /data/config.properties
  tty: true