Create and Deploy CH5 Archives

CH5 projects are essentially web applications that consist of many HTML, CSS, JS, PNG, and other files. For simplicity in handling and versioning as well as for compatibility with existing tools, the various files that comprise a CH5 project are archived into one large ZIP file with a .ch5z extension.

NOTE: The CH5 project archive is only a ZIP file. The ZIP file should have a hierarchical structure if required by the application directory format.

CH5 supports utilities for creating and deploying project archives. These utilities are run using a command line interface.

  • The ch5 cli-archive utility creates a zip file that can be deployed to either a touch screen or a control system.
  • The ch5 cli-deploy utility sends the zip file created with the archive utility to a touch screen or control system.

Installation

To put the ch5-cli scripts onto a workstation for archive and deployment:

  1. Install Node.js/NPM as described at https://nodejs.org/en/.
    • Minimum Node.js version: 24.18.0
    • Minimum NPM version: 11.16.0
  2. Install the Crestron utilities CLI:
    • On a Windows® operating system workstation, open the command prompt and issue the following commands:
      • Copy 
      npm install -g @crestron/ch5-utilities-cli

      npm install -g @crestron/ch5-shell-utilities-cli
    • On a macOS® operating system workstation, open the command prompt and issue the following commands:
      • Copy 
      sudo npm install -g @crestron/ch5-utilities-cli

      sudo npm install -g @crestron/ch5-shell-utilities-cli

Archive Commands

Issue the ch5-cli --help command to view a description of all parameters for the archive utility. A description of the functions of each command is also provided.

The following parameters are commonly used:

  • -p, --project-name: Indicates the base file name of the outputted project archive file.
  • -d, --directory-name: Indicates the directory that will be compressed to a single file.
  • -o, --output-directory: Indicates the file system directory location of the outputted archive.
  • -c, --contract-file: Indicates the location and file name of the CH5 Contract Editor output that is associated with the project.

Usage Examples

The following examples show how the command line interface is used to create a Crestron HTML5 (.ch5z) archive file.

Copy 
ch5-cli archive -p my_project -d dist/prod/Shell -o dist/prod -c ../../contract/output/my_contract/interface/mapping/my_contract.cse2j

Each parameter has the following usage:

  • Creates an output file called my_project.ch5z using the “-p my_project” parameter
  • Pulls the project content, typically the output of a module bundler such as webpack, from the dist/prod/Shell directory using the “-d dist/prod/Shell” parameter
  • Puts the output file into directory dist/prod using the “-o dist/prod” parameter
  • Applies a ../../contract/output/my_contract/interface/mapping/my_contract.cse2j contract file to the archive using the “-c ../../contract/output/my_contract/interface/mapping/my_contract.cse2j” parameter

Deploy Archive Commands

Once the archive is generated, it can be deployed using Crestron Toolbox software. For touch screens, .ch5z files can be deployed like Smart Graphics-based .vtz files. For HTML5 Web XPanel usage, .ch5z files can be deployed using the Web Pages and Mobility Projects function in Crestron Toolbox.

To make iterative incremental testing easier for CH5 developers, the ch5‑cli utility is provided to make deployment available within the same tools used to create the project and the project archive.

Issue the ch5-cli deploy –help command to view description of all parameters for deploying a .ch5z archive.

The following parameters are commonly used:

  • -H, --deviceHost: The IP Address or DNS accessible host name of the touch screen or control system to deploy the archive.
  • -t, --deviceType: The device type and deployment:
    • touchscreen: Deploys to a touch screen.
    • web: Deploys to a control system as an HTML5 Web XPanel project.
    • mobile: Deploys to a control system as a mobile project (coming soon).
    • controlsystem: Deploys to a control system as both an HTML5 Web XPanel and mobile project.
  • -p, --prompt-for-credentials: The utility will prompt on the console for the user ID and password of the device.

Considerations for Credentials

Crestron does not promote any practices that encourage putting credentials into scripts. Therefore, the deploy utility will not have any ability to provide a user ID and password.

There are two alternatives for entering credentials each time you deploy an archive using the ch5-cli deploy utility:

  • Environment variables CH5CLI_DEPLOY_USER and CH5CLI_DEPLOY_PW will be honored as the user ID and password if the -p/--prompt-for-credentials parameter is not provided and the both environment variables are set and not empty.
  • Use certificate-based authentication, providing the private key with the -i/--identity-file parameter and the username with the -u/ --identity-user parameter. To use this feature:
    • Create a public/private key pair using openssl ssh-keygen.
    • Upload the .pub file to the /User folder of the device.
    • Using the device console as an admin user, use console command SSHSERVER ADDUSERKEY -N:USERNAME -K:FILENAME.PUB
    • Log out of the device.

Slow Mode

If projects are not deploying correctly, slow mode can be enabled to upload the project files at a slower speed. For more information, refer to Slow Mode (CH5 CLI Deploy).

Usage Examples

The following example shows how the command line interface is used to deploy a Crestron HTML5 (.ch5z) archive file:

Copy 
ch5-cli deploy -p -H 1.1.1.1 -t touchscreen dist/prod/my_project.ch5z

Each parameter has the following usage:

  • Deploys the “dist/prod/my_project.ch5z” file.
  • Deploys to the device at IP address 1.1.1.1 using the “-H 1.1.1.1” parameter.
  • Deploys the project as a touch screen project with the “-t touchscreen” parameter.
  • Prompts for credentials with the “-p” parameter.