Install and start HPS

Prerequisites

Set GitHub token

To download HPS core services from the GitHub Container Registry, you need a GitHub Personal Access Token (PAT) with the appropriate scopes.

1. Create a Personal Access Token (PAT) in GitHub. Note it down immediately after creating it as you will not be able to see it again.

2. Click on the token name, select the repo and write:packages scopes, and update the token.

3. Click on Configure SSO and authorize both ansys.

4. Set your GitHub PAT as an environment variable GITHUB_TOKEN.

Windows

$env:GITHUB_TOKEN = “<token>”

Linux

export GITHUB_TOKEN=”<token>”

Warning

If you are using VS Code, you need to close all instances for the environment variable to take effect.

Install Docker

Docker is required to run HPS.

Windows

Either install Docker Desktop (may require a Docker subscription depending on your organization) or run Docker CE (Community Edition, which is open-source) in WSL (Windows Subsystem for Linux).

If using Docker CE:

1. If you don’t have WSL installed, follow the official Microsoft How to install Linux on Windows with WSL documentation.

2. Follow the official Docker installation guide to install Docker Engine and Docker Compose on WSL.

Linux

1. Install Docker CE - instructions here for Linux.

2. Add your user to the docker group:

sudo gpasswd -a $USER docker
newgrp docker

Set the MACHINE_IP environment variable

The MACHINE_IP environment variable must be set to the IP address of your machine.

Running Docker with WSL (Windows)

If you are using WSL to run Docker, the MACHINE_IP is the WSL IP address of your machine.

1. Find the WSL IP address:

   1. Open a WSL terminal and run the following command:

      ip addr show eth0
      

   2. Find the inet line under the eth0 section.

   3. Note the IP address, which is the number before the /.

2. Add the MACHINE_IP environment variable:

   1. Click the Environment Variables button.

   2. Under System Variables, click New.

   3. Enter MACHINE_IP as the variable name.

   4. Set the WSL IP address you noted in the previous step as the value.

   5. Click OK to save the variable.

Running Docker with Docker Desktop (Windows)

If you are using Docker Desktop to run Docker, use your machine’s Wireless or Ethernet IP address, as follows:

• If connected via Wi-Fi, use the IP address from the Wireless LAN adapter Wi-Fi section.

• If connected via Ethernet, use the IP address from the Ethernet adapter Ethernet section.

1. Find the machine IP address:

   1. Open a terminal and run the following command:

   ipconfig /all
   

   2. Locate the Ethernet adapter Ethernet or Wireless LAN adapter Wi-Fi section.

   3. Note the IP address under IPv4 Address.

2. Add the MACHINE_IP environment variable:

   1. Click the Environment Variables button.

   2. Under System Variables, click New.

   3. Enter MACHINE_IP as the variable name.

   4. Set the WSL IP address you noted above as the value.

   5. Click OK to save the variable.

Warning

If you are using VS Code, you need to close all instances for the environment variable to take effect.

Deploy the core services

Follow these steps to start and verify the HPS core services.

Start HPS core services

Follow these steps to deploy the Ansys HPS core services using Docker Compose on your machine.

See also

For more detailed instructions, see Deploying Core Services with Docker Compose in the Ansys HPC Platform Services Deployment Guide.

1. Ensure that Docker is installed and that the MACHINE_IP environment variable is set (see above).

2. Navigate to the supported HPS version listed in the supported software table to know which version to download.

3. Download HPS core services.

   1. Go to the Ansys Customer Portal.

   2. Navigate to Downloads > Current release >Platform Components > HPC Platform Services.

   3. Download HPS-Core (docker compose) (docker-compose-internal.tar.gz).

   Important

   SAF is only tested against the supported HPS version listed in the supported software table. You can try other versions but they may not work correctly.

4. Extract the downloaded file. Extract the docker-compose-customer.tar.gz file:

   tar -xvf docker-compose-customer.tar.gz
   

   A folder named docker-compose-customer is extracted.

5. Navigate to the extracted folder:

   cd docker-compose-customer
   

6. Log in to the Docker Registry. Authenticate with your GitHub username and personal access token (PAT):

   docker login ghcr.io/ansys
   

   Note

   If you have lost or forgotten your PAT, follow the steps in GitHub Docs: Creating a personal access token to generate a new one. Make sure it has the read:packages scope.

7. Update the environment variables file.

   1. In a text editor, open the environment variables file. This is the .env file located in the docker-compose-customer folder.

   2. Locate the following line:

      EXTERNAL_NAME=localhost
      

   3. In this line, replace localhost with your machine’s IP (MACHINE_IP), so it reads:

      EXTERNAL_NAME=${MACHINE_IP}
      

   4. Save the file.

8. Start the HPS core service containers.

   docker-compose up -d
   

   Note

   The first time you run this command, it takes time to build the image and download the required third-party containers. You can expect subsequent runs to be faster.

Verify HPS core services

Follow these steps to verify that the HPS core services started correctly.

1. Open this URL in a web browser:

   https://<MACHINE_IP>:8443/hps
   

2. Access the HPS web app.

   1. Click the JMS Web UI button to access the HPS web app.

   2. Log in using the default administrative credentials:

      • Username: repadmin

      • Password: repadmin

If you completed these steps successfully, the HPS core services have been started correctly.

Deploy a static evaluator or an autoscaling service

You can deploy either a static evaluator or an autoscaling service to run jobs on your machine. Refer to the official documentation for more details on each option.

Deploy a static evaluator

See also

For more detailed instructions, see Deploying Static Evaluators in the Ansys HPC Platform Services Deployment Guide.

Follow these steps to start and verify the HPS evaluator.

Start the HPS evaluator

Follow these steps to deploy the HPS evaluator on your machine.

See also

For more detailed instructions, see Deploying Core Services with Docker Compose in the Ansys HPC Platform Services Deployment Guide.

1. Download the HPS evaluator.

   1. Go to the Ansys Customer Portal.

   2. Navigate to Downloads > Current release > Platform Components > HPC Platform Services.

   3. Download the evaluator file that corresponds to your operating system:

      Windows

      Click hps-evaluator (Windows) to download rep-evaluator-windows-signed.tgz.

      CentOS 8 or later, Ubuntu

      Click hps-evaluator (ubuntu20_04) to download rep-evaluator-default.tgz.

      CentOS 7

      Click hps-evaluator (Centos7) to download rep-evaluator-centos7.tgz.

2. Extract the archive.

   For example, on Windows:

   tar -xvf rep-evaluator-windows-signed.tgz
   

3. Navigate to the extracted folder.

   cd rep-evaluator-windows-signed
   

   The folder contains the rep-evaluator.exe file.

4. Log in to the controller.

   The evaluator must be able to communicate with the services on the controller. This is done by logging in to the controller from the evaluator.

   At the command prompt, run the rep-evaluator executable’s login command with the following arguments:

   Windows PowerShell

   ./rep-evaluator.exe login --url https://$($env:MACHINE_IP):8443/rep --username repadmin --password repadmin
   

   Linux Bash

   ./rep-evaluator login --url https://$MACHINE_IP:8443/rep --username repadmin --password repadmin
   

5. Start the evaluator.

   Once you are logged in, run this command to start the evaluator:

   Windows

   ./rep-evaluator.exe
   

   Linux

   ./rep-evaluator
   

The evaluator should now be available on the Resources page of the Ansys HPC Manager.

Verify the HPS evaluator

Follow these steps to ensure that the HPS evaluator is running correctly.

1. Go to the Ansys HPC Manager Resources page.

2. Confirm that the evaluator is listed as a resource.

Deploy an autoscaling service

Refer to the HPS official documentation to deploy and configure an autoscaling service.