Project Setup

Note

Please follow the instructions below to set up your computational project in HEAppE Middleware.

After the succesfull deployment of HEAppE Middleware, you can access the HEAppE Middleware REST API interface.

The Swagger is available at the following URL:

http://localhost:5000/swagger/index.html

Warning

HEAppE Middleware is deployed on port 5000 by default. If you have changed the port in the .env file, please use that port instead.

1. Create a new project

To create a new project in HEAppE Middleware, follow these steps:

Open the Swagger UI in your web browser.
Authenticate using your credentials. And store provided sessionCode.
Use the POST method to create a new project.
Fill in the required fields:
- SessionCode: The session code you received after authentication.
- Name: The name of your project.
- Description: A brief description of your project.
- AccountingString: The accounting string for your project (slurm/pbs account).
- StartDate: The start date of your project.
- EndDate: The end date of your project.
- UsageType: The type of usage for your project (e.g., research, production).
- UseAccountingStringForScheduler: Whether to use the accounting string for the scheduler.
- PIEmail: The email address of the Principal Investigator (PI) for your project.
Click the Execute button to create the project.

Example of a project creation request:

Note

The following example uses the curl command to create a new project. You can also use other HTTP clients or programming languages to make the request.

curl -X 'POST' \
'https://localhost:5000/heappe/Management/Project' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "SessionCode": "<sessionCode>",
    "Name": "MyProject",
    "Description": "My project description",
    "AccountingString": "my_accounting_string",
    "StartDate": "2025-04-14T07:33:12.344Z",
    "EndDate": "2026-04-14T07:33:12.344Z",
    "UsageType": 1,
    "UseAccountingStringForScheduler": true,
    "PIEmail": "support.heappe@it4i.cz
    }'"

Note

The UsageType field is an integer value that represents the type of usage for your project. The following values are available:

1: CoreHours
2: NodeHours

After the project is created, you will receive a response with the project ID and other details.

2. Project to Cluster Assignment

To map your project to a cluster, follow these steps:

Open the Swagger UI in your web browser.
Authenticate using your credentials. And store provided sessionCode.
Use the POST method to assign your project to a cluster.
Fill in the required fields:
- SessionCode: The session code you received after authentication.
- ProjectId: The ID of your project.
- ClusterId: The ID of the cluster you want to assign your project to.
- LocalBasepath: The local base path for your project on the cluster (project scratch storage basepath).
Click the Execute button to assign the project to the cluster.

Example of a project to cluster assignment request:

Note

The following example uses the curl command to assign a project to a cluster. You can also use other HTTP clients or programming languages to make the request.

curl -X 'POST' \
'https://localhost:5000/heappe/Management/ProjectAssignmentToCluster' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "SessionCode": "<sessionCode>",
    "ProjectId": 1,
    "ClusterId": 1,
    "LocalBasepath": "/scratch/my_project"
    }'

Note

The ProjectId and ClusterId fields are integer values that represent the IDs of your project and the cluster, respectively. You can find these IDs in the response from the project creation request or by using the GET method to retrieve a list of projects or clusters.

3. Robot/Service Account Creation and SSH Key Generation

To create a robot/service in HEAppE Middleware, follow these steps:

Open the Swagger UI in your web browser.
Authenticate using your credentials. And store provided sessionCode.
Use the POST method to create a new robot/service account.
Fill in the required fields:
- SessionCode: The session code you received after authentication.
- ProjectId: The ID of your project.
- Username: The username for the robot/service account.
- Password: The password for the robot/service account.

Note

The following example uses the curl command to create a new robot/service account. You can also use other HTTP clients or programming languages to make the request.

curl -X 'POST' \
'https://localhost:5000/heappe/Management/GenerateSecureShellKey' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "SessionCode": "<sessionCode>",
    "Credentials": [
        {
            "Username": "my_robot_account",
            "Password": "my_robot_password"
        }
    ],
    "ProjectId": 1
    }'

Warning

Password is not mandatory. Please fill password only if you want to set SSH Key & Password authentication. If you do not want to set password, please leave it empty - depends on your cluster configuration.

System will always generate SSH Key and uses randomly generated passphrase for the SSH Key. Then the Private Key is stored into the Credentials Secure Vault.

Note

The ProjectId field is an integer value that represents the ID of your project. You can find this ID in the response from the project creation request or by using the GET method to retrieve a list of projects.

Also the public key is returned in the response. You can use this public key to configure the SSH access to the cluster.

4. Robot/Service Account SSH Key Propagation

heappe/Management/GenerateSecureShellKey endpoint returns the public key for the robot/service account. You need to propagate this public key to the cluster where your project is assigned. This step is necessary to allow the robot/service account to access the cluster via SSH.

5. Robot/Service Account project initialization

To initialize the robot/service account for your project, follow these steps:

Open the Swagger UI in your web browser.
Authenticate using your credentials. And store provided sessionCode.
Use the POST method to initialize the robot/service account.
Fill in the required fields:
- SessionCode: The session code you received after authentication.
- ProjectId: The ID of your project.
- ClusterProjectRootDirectory: The root directory for your project on the cluster (non temporary storage basepath).
Click the Execute button to initialize the robot/service account.

Example of a robot/service account initialization request:

Note

The following example uses the curl command to initialize the robot/service account. You can also use other HTTP clients or programming languages to make the request.

curl -X 'POST' \
'https://localhost:5000/heappe/Management/InitializeClusterScriptDirectory' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "SessionCode": "<sessionCode>",
    "ProjectId": 1,
    "ClusterProjectRootDirectory": "/home/my_project"
    }'

Note

The ProjectId field is an integer value that represents the ID of your project. You can find this ID in the response from the project creation request or by using the GET method to retrieve a list of projects.

The ClusterProjectRootDirectory field is a string value that represents the root directory for your project on the cluster. This directory should be accessible by the robot/service account and should have the necessary permissions for file operations.

Optional: Test Robot Account cluster access

To test the cluster access for the robot/service account, follow these steps:

Open the Swagger UI in your web browser.
Authenticate using your credentials. And store provided sessionCode.
Use the GET method to test the cluster access for the robot/service account.
Fill in the required fields:
- SessionCode: The session code you received after authentication.
- ProjectId: The ID of your project.
- Username: The username for the robot/service account (e.g., my_robot_account).
Click the Execute button to test the cluster access for the robot/service account.

Example of a robot/service account cluster access test request:

Note

The following example uses the curl command to test the cluster access for the robot/service account. You can also use other HTTP clients or programming languages to make the request.

curl -X 'GET' \
'https://localhost:5000/heappe/Management/TestClusterAccessForAccount?Username=my_robot_account&ProjectId=1&SessionCode=<sessionCode>' \
-H 'accept: application/json'

Note

If test is successful, you will receive a response with the status code 200 and a message indicating that the cluster access test was successful. If the test fails, you will receive an error message with details about the failure.