Automated Helix DAM deployment

Important

The command-line deployment is currently a Technology Preview. Features offered in Technology Preview are experimental and not guaranteed to always work as expected. If you have feedback and functionality suggestions, email techpreview@perforce.com.

You can deploy Helix DAM and its required components automatically using the Helix TeamHub CLI. This deployment method is faster and requires fewer steps than the manual deployment. It provides a minimal Helix DAM setup and is the best way to get a Helix DAM evaluation up and running quickly.

You can use the CLI to deploy Helix DAM on premises or in your own cloud environment.

The following information provides everything you need to know for deploying Helix DAM using the TeamHub CLI. To learn more about the TeamHub CLI, see the Helix TeamHub CLI User Guide.

Components deployed

The following components are automatically installed and configured during deployment:

  • Elasticsearch instance – Helix DAM uses Helix Search in conjunction with Elasticsearch to index asset information used to search for assets.

  • Helix Search – An API used by Helix DAM to search and automatically tag your assets.

  • Helix DAM – A web-based interface that streamlines the process of finding, reviewing, using, repurposing, and sharing assets. Helix DAM is built on top of Helix TeamHub. When you deploy Helix DAM, a standard setup is automatically deployed. The Helix TeamHub packages used during the deployment contain Helix DAM.

Helix Core Server must already be installed and configured before Helix DAM deployment. See Helix Core Server installation and requirements.

Before deployment

Make sure the following requirements are met before starting Helix DAM deployment.

Helix Core Server installation and requirements

Helix Core Server must be installed. If it is not installed, see Helix Core Server is not installed for deployment options.

Helix DAM requires the following information and setup for the Helix Core Server:

  • Helix Core Server hostname and port (P4PORT) (master server or commit server in a commit/edge environment)

    • Only assets stored in Helix Core Server Stream depots or classic (local) depots are available in Helix DAM.

      Helix DAM works with supported versions of Helix Core Server (Standard Maintenance).

      The versions supported in this release of Helix DAM are (latest patch of server version required):

      • Helix Core Server 2022.1 - minimum recommended version, Helix Core Server 2022.1 and later contain performance improvements over earlier versions

      • Helix Core Server 2022.2

      • Helix Core Server 2023.1

      • Helix Core Server 2023.2

      We recommend a server security level of +1. For more information, see Server security levels in Helix Core Server Administrator Guide.

      Note

      Make sure that the names of Helix Core Server users that need access to Helix DAM do not exceed 100 characters. Helix DAM only supports usernames up to 100 characters.

  • Fingerprint for Helix Core Server if it is running SSL. Run the p4 trust command in the P4 command line.

  • Super user on Helix Core Server with super permissions, unlimited timeouts, and an all hosts ticket. If you already have a super user with these settings, you can use it for Helix DAM. You need to username and password/ticket. If you need to add a super user, see Creating a super user on the Helix Core Server.

  • Character set (P4CHARSET) used on Helix Core Server for translation of Unicode files.

  • An entry in the protections table for all users that need access to Helix DAM. To learn more, see Setting protections with p4 protect in Helix Core Server Administrator Guide. The user used for integration will need super access in the protections table to view and manage protections.

Other requirements

Make sure the following prerequisites are met:

  • Hardware - Review hardware requirements for Elasticsearch and Helix DAM. We do not recommend installing all components on the same server except for evaluation purposes. If all components on the same server, the minimum memory requirement is 8 GB.

  • Firewall

  • Operating system

Deployment overview

The deployment automatically detects the operating system of the servers you specify to host the Elasticsearch, Helix Search, and Helix DAM installations, installs the required packages and dependencies, and performs configuration steps. MongoDB, Redis, and Elasticsearch credentials are automatically assigned during deployment.

To deploy Helix DAM using the CLI, perform the following steps.

  1. Install the Helix TeamHub CLI

  2. Provide the deployment information for Helix Core, Elasticsearch, Helix Search, and Helix DAM

  3. Verify the deployment information

  4. Deploy the components

  5. Verify the deployment

  6. Set up user and group synchronization, and enable background jobs

  7. Modify Elasticsearch settings

There is also optional configuration you may choose to do after deployment.

Step 1: Install Helix TeamHub CLI

You need the Helix TeamHub CLI to deploy Helix DAM.

  1. Download Helix TeamHub CLI for your operating system. Helix TeamHub CLI is supported on Linux, macOS, and Windows.

  2. When the download is complete, extract the files and access the binary in the bin folder from a command prompt.

    You can now set up the deployment information.

Important

Do not run hth setup or follow the hth-cli help. They are intended for use with existing Helix TeamHub installations. Only use the following instructions for initial Helix DAM deployment.

Step 2: Provide the deployment information

Before deployment, you need to provide information about each component in the following order:

  • Helix Core

  • Elasticsearch

  • Helix Search

  • Helix DAM

To set up the deployment information, follow the prompts in Helix TeamHub CLI. Use the arrows to move up and down to select options. Press Enter to confirm selections and submit entered values.

  1. From a command prompt, enter hth admin setup.

    Tip

    To open this help from the CLI, select [show help].

  2. To create a deployment, select [create].

  3. Enter a Deployment Name that uniquely identifies the deployment.

  4. Select [edit components].

Helix Core Server

Provide details about your Helix Core Server, which must be installed before deploying Helix DAM.

  1. Select [create].

  2. Select Helix Core Server.

  3. Select [edit details].

  4. Enter or select the Helix Core Server information.

    Value Description More information
    P4PORT Hostname or IP address and port for your Helix Core Server in the following format: host:port or ssl:host:port.  
    Username Username for a Helix Core Server user with super privileges and an unlimited ticket timeout. Must be 2 - 100 characters. Cannot contain spaces. Valid characters: A-Z, a-z, 0-9,-, _ Creating a super user on the Helix Core Server
    Password or Ticket Password or ticket generated for the super user. The super user must have unlimited ticket timeout and an all hosts ticket.
    		 Creating a super user on the Helix Core Server
    Charset P4CHARSET used by the Helix Core Server Setting up a server for Unicode in Helix Core Server Administrator Guide
    Fingerprint (if SSL) If you connect to Helix Core Server using an SSL connection, enter the fingerprint of the key received for SSL connections. To get the existing fingerprint, run the p4 trust -1 command in the P4 command line. p4 trust in Helix Core Command-Line (P4) Reference

  5. Select [back] until Helix Core Server is displayed.

    Helix Core Server configuration is complete and you can now configure Elasticsearch.

Elasticsearch

Provide details about the computer to install Elasticsearch on.

If you have an existing Elasticsearch instance to use, enter the information for it. Helix DAM supports Elasticsearch 8.0.x to 8.12.x. Helix Search may support different versions of Elasticsearch. Make sure you use a version supported by Helix DAM.

  1. Select [create].

  2. Select Elasticsearch.

  3. Select [edit servers].

  4. Select [create].

  5. Enter the Hostname or IP Address for the computer to install Elasticsearch on.

  6. Select [edit ssh configuration].

  7. Enter or select the following information.

    Value Description
    Port SSH protocol port. Default port is 22.
    Username Source Source for the username to log in to the computer that will host Elasticsearch:

    • system - Use the current logged in user on the local computer.

    • custom - Use a specified username.
    Authentication Method Authentication method used to log in to the computer that will host Elasticsearch using SSH:

    • agent - Use an SSH agent configured on your computer.

    • key - Use an SSH key. Enter the path and password.

    • protected_key - Use a password-protected SSH key. Enter the path and password.

    • password - Use a password. Enter the password.

  8. Select [back] until Helix Core Server and Elasticsearch are displayed.

    Elasticsearch configuration is complete and you can now configure Helix Search.

Helix Search

Provide details about the computer to install Helix Search on.

  1. Select [create].

  2. Select Helix Search.

  3. Select [edit servers].

  4. Select [create].

  5. Enter the Hostname or IP Address for the computer to install Helix Search on.

  6. Select [edit ssh configuration].

  7. Enter or select the following information.

    Value Description
    Port SSH protocol port. Default port is 22.
    Username Source Source for the username to log in to the computer that will host Helix Search:

    • system - Use the current logged in user on the local computer.

    • custom - Use a specified username.
    Authentication Method Authentication method used to log in to the computer that will host Helix Search: using SSH:

    • agent - Use an SSH agent configured on your computer.

    • key - Use an SSH key. Enter the path and password.

    • protected_key - Use a password-protected SSH key. Enter the path and password.

    • password - Use a password. Enter the password.

  8. Select [back] until Helix Core Server, Elasticsearch, and Helix Search are displayed.

    Helix Search configuration is complete and you can now configure Helix DAM.

Helix Digital Asset Management (DAM)

Provide details about the computer to install Helix DAM on and additional configuration information.

  1. Select [create].

  2. Select Helix Digital Asset Management (DAM).

  3. Select [edit details].

  4. Enter the following information.

    Value Description
    Hostname Helix DAM instance hostname. Helix DAM uses this hostname in URLs, email links, and API requests. Even though Helix DAM can be configured to use an IP address or another hostname assigned to the server, a delegated alias (CNAME) or name (A) is recommended to simplify future server relocation.
    Email Email address to use for all outgoing Helix DAM emails
    Default Company Default company short name (company ID) to use for logging in. Must be 2 - 100 characters. Cannot contain spaces. Valid characters: A-Z, a-z, 0-9,-, _
    Integration Bot Name (dam-integ-bot) Name of a company admin bot used by Helix Core extensions to call the Helix DAM API. Must be 2 - 100 characters. Cannot contain spaces. Valid characters: A-Z, a-z, 0-9,-, _

  5. Select [edit servers].

  6. Select [create].

  7. Enter the Hostname or IP Address for the computer to install Helix DAM on.

  8. Select [edit ssh configuration].

  9. Enter or select the following information:

    Value Description
    Port SSH protocol port. Default port is 22.
    Username Source Source for the username to log in to the computer that will host Helix DAM:

    • system - Use the current logged in user on the local computer.

    • custom - Use a specified username.
    Authentication Method Authentication method used to log in to the computer that will host Helix DAM: using SSH:

    • agent - Use an SSH agent configured on your computer.

    • key - Use an SSH key. Enter the path and password.

    • protected_key - Use a password-protected SSH key. Enter the path and password.

    • password - Use a password. Enter the password.

  10. Select [back] until [exit] is displayed.

  11. Select [exit].

    Deployment configuration is now complete. You can now verify the deployment information.

Step 3: Verify the deployment information

Before running the deployment, consider using the automated verification to ensure the configuration is ready to deploy. You can also manually verify that all information you entered and selected for each component is correct. The information is written to the admin_config.json file in the user's home directory. To learn more about the configuration file, see Admin configuration file.

Automated verification

  1. Enter hth admin verify and press Enter.

  2. Select the verification tests to run.

    Value Description
    Check SSL connection Verifies the connections to all the servers in the configuration.
    Check if 'sudo' command is available without a password Verifies that you can run the sudo command on all servers in the configuration without a password.
    Check if operating system and version are supported Verifies that the operating systems and versions of the servers in the configuration can run the required components.
    Check server resources Verifies that the memory, number of processors, and storage of the servers in the configuration can run the required components.
    Check Helix Core configuration and connection Verifies the connection to Helix Core server, the fingerprint, and the license.

  3. Press Enter.

    If there are any failures, use the information displayed to fix the errors.

    You can now start deployment. See Step 4: Deploy the components.

Manual verification

  1. Enter hth admin config show.

    The configuration info is displayed. To learn more about the values, see Admin configuration file.

  2. Review the information for accuracy.

  3. To make any changes, enter hth admin config edit.

    The configuration file opens in your default editor for JSON files.

  4. Make any changes.

  5. Save the file.

    You can now start deployment. See Step 4: Deploy the components.

Step 4: Deploy the components

After specifying and verifying information for all components, you can start deployment.

Keep in mind that it may take several minutes to deploy some components depending on the component and connection speed.

  1. Enter hth admin deploy -v.

  2. Select the deployment you configured.

  3. Select the component to deploy. Components must be deployed in the following order:

    • Elasticsearch

    • Helix Search

    • Helix DAM

  4. Select the server to deploy the component to.

  5. Repeat steps 3 and 4 to deploy the remaining components.

    When deployment of all components is complete, verify they are working correctly.

Step 5: Verify the deployment

Verify successful deployment of Helix DAM and the other components using a browser.

Step 6: Set up user/group synchronization and enable background jobs

You can set up user and group synchronization with Helix Core Server. Then, you must manually enable Helix DAM background jobs.

  1. Log in to the Helix TeamHub admin UI. See Logging in to the Helix TeamHub admin UI.

  2. Click Preferences.

  3. Go to the Account and group synchronization area.

  4. Make any changes. To learn more about the available settings, see Managing users and groups in Helix Core Server.

  5. Click Save preferences.

  6. Connect to the Helix DAM server via SSH and run the following commands to apply the server changes and enable the background jobs:

    sudo hth-ctl reconfigure

    sudo hth-ctl start resque_scheduler

Step 7: Modify Elasticsearch settings

The Helix DAM deployment provides minimal configuration for Elasticsearch. You must perform additional configuration before Elasticsearch is ready for use in your production environment.

Review and modify settings the Elasticsearch configuration file, which is located in /etc/elasticsearch/elasticsearch.yml.

To learn more about the required Elasticsearch configuration, see the Elasticsearch help.

Optional configuration after deployment

When deployment is complete, you may want to perform additional configuration for your deployment. This additional configuration is optional.

Modify memory limits for Helix Search and Elasticsearch

By default, the Helix Search and Elasticsearch services are limited by memory usage. You may want to adjust the limits in the configuration files to allocate sufficient memory for your deployment.

Change the -Xms (minimum memory) and -Xmx (maximum memory) values in the following files:

  • Helix Search - /opt/perforce/helix-p4search/sbin/p4search.vmoptions

  • Elasticsearch - /etc/elasticsearch/jvm.options

Configure additional Helix DAM settings

You may want to configure the following Helix DAM settings for your deployment.

Configure auto-tagging for Helix DAM assets in Helix Search

If you want to use auto-tagging for Helix DAM assets, configure auto-tagging in Helix Search. To learn more, see Image auto-tagging configuration in the Helix Core Search Developer Guide.