Local HPC Simulator Deployment Expert Guide

The following text describes how to deploy HEAppE Middleware and connect it to the Local Simulator of the HPC. The Local Simulator runs at Docker container and consists of the scripts that simulate the HPC environment to test the HEAppE Middleware.

Step 1: HEAppE environment setup - Prerequisites

Local Environment (deploy on user machine)
For running a test instance of HEAppE Middleware is necessary to have an operating system with Docker support and the computer must have at least 2 GB of free RAM.
Software installation
Docker

Docker Compose

2. HEAppE environment setup

These steps do as sudo user (recommended). In case of a misunderstanding of folder structure, please move to the end of this chapter and see folder validation scheme.

Create the HEAppE Middleware directory structure
Copy the following bash script to the server and execute it. This script sets up the necessary directory structure for the HEAppE Middleware.

Download the script here: HEAppE-dir-structure.sh

Grant execution permissions to the script.
chmod +x HEAppE-dir-structure.sh
Run the script with the project name argument as a sudo user.
./HEAppE-dir-structure.sh LocalHPCSimulatorHEAppE
Note

The script creates the following directory structure:
/opt/heappe ├── confs └── projects └── LocalHPCSimulatorHEAppE ├── app │ ├── keys │ ├── logs │ └── confs ├── ssh_agent │ └── keys └── docker_configurations
Prepare .env file for docker containers
Copy the following .env file into the directory /opt/heappe/projects/LocalHPCSimulatorHEAppE/docker_configuration/.

You can modify the file according to your needs - set container names, database master password, etc.

Download the .env file here: .env
cp .env /opt/heappe/projects/LocalHPCSimulatorHEAppE/docker_configuration/
Prepare docker-compose.override.yml file for docker containers
Copy the following docker-compose.override.yml file into the directory /opt/heappe/projects/LocalHPCSimulatorHEAppE/docker_configuration/.

You can modify the file according to your needs - set container names, database master password, etc. But specify the database password same as in the .env file.

Download the docker-compose.override.yml file here: docker-compose.override.yml
cp docker-compose.override.yml /opt/heappe/projects/LocalHPCSimulatorHEAppE/docker_configuration/

Get the release of HEAppE Middleware official repository and copy docker-compose files

cd /opt/heappe/projects/LocalHPCSimulatorHEAppE/
git clone https://github.com/It4innovations/HEAppE.git heappe-core
cp /opt/heappe/projects/LocalHPCSimulatorHEAppE/docker_configuration/docker-compose.override.yml heappe-core
cp /opt/heappe/projects/LocalHPCSimulatorHEAppE/docker_configuration/.env heappe-core

git clone https://github.com/It4innovations/HEAppE-scripts.git
mv  HEAppE-scripts/LocalHPC heappe-core
rm -rf HEAppE-scripts

3. HEAppE configuration files preparation

In order to configure the HEAppE environment, some additional setup files need to be prepared (appsettings.json, appsettings-data.json and seed.njon). The first mandatory configuration file is appsettings.json, which includes key values about user domain parameters, business logic, or HPC connection framework. For instance, the template of the configuration file is stored at HEAppE/RestApi/appsettings.example.json. The following section describes appsettings.json in detail. The configuration code is divided into separate blocks and explained individually.

`appsettings.json` configuration

The HEAppE database connection string is an important setting. A database connection string is a string that specifies information about a data source and the means of connecting to it (see the below example for the Microsoft SQL Server connection string).
"ConnectionStrings": {
    "MiddlewareContext": "Server=mssql;Database=heappe;User=SA;Password=<mssql_password>;TrustServerCertificate=true;",
    "Logging": ""
}
Note

Store appsettings.json into the directory /opt/heappe/projects/LocalHPCSimulatorHEAppE/app/confs.

More information about other sections of the configuration file is available at the REST API configuration.

Warning

Please check the password policy of the Microsoft SQL Server. The password must meet the requirements of the SQL Server password policy.

`appsettings-data.json` configuration

For the HEAppE Middleware Data Staging API configuration, you need to prepare the appsettings-data.json file. You need to specify same database connection string as in the appsettings.json file and also specify AuthenticationToken at ApplicationAPIConfiguration section of the file.
"ConnectionStrings": {
    "MiddlewareContext": "Server=mssql;Database=heappe;User=SA;Password=<mssql_password>;TrustServerCertificate=true;"
}
"ApplicationAPIConfiguration": {
    "AuthenticationToken": "<token>"
}
Note

Store appsettings-data.json into the directory /opt/heappe/projects/LocalHPCSimulatorHEAppE/app/confs.

More information about other sections of the configuration file is available at the Data Staging API configuration.

`seed.njson` configuration

Another requirement for seamless functionality of the HEAppE Middleware is seed.njson file creation (database seed setup). When HEAppE is starting up database seed is applied.

An example template for HPC Cluster mode configuration seed is presented at the URL address HEAppE/RestApi/seed.localcomputing.example.njson

Note

Store seed.njson into the directory /opt/heappe/projects/LocalHPCSimulatorHEAppE/app/confs.

Warning

If you want to use specific configuration, you can modify the seed.njson file according to your needs. You can find more information about seed.njson file at the Database seed.

4. HEAppE Middleware instance launching

Build Docker containers

For building containers (HEAppE, Database, etc..) use docker compose tool (multi-container Docker is specified in docker-compose.yml file).
$ cd /opt/heappe/heappe-core
$ docker compose build

Init and unseal Credentials Vault

Before the HEAppE Middleware deployment, the Vault needs to be initialized and unsealed. Initialization is a one-time process that sets up the Vault’s encryption keys and other configuration settings. During initialization, the Vault generates the initial root token and unseal keys, which are required to unseal the Vault.

The scripts can be also used for unsealing the Vault when it is sealed and already initialized, usage is the same as for initialization.

Note

Tis workflow requires ansible-vault and jq to be installed.

1. Navigate to the Vault scripts directory:
$ cd /opt/heappe/heappe-core/HashiCorpVaultScripts
2. Add execute permissions to the init and unseal scripts:
$ chmod +x *.sh
3. Run the initialization script:
$ ./initHVault.sh myVaultPassword -p /opt/heappe/projects/credentials -b ../../app/confs -i HPC_PROJECT
Note

If configuration files do not exist in the specified base path, default configuration files will be created.

Start Docker containers

Use the code below to start the HEAppE Middleware running containers. Running containers start listening on ports defined in .env file.
$ cd /opt/heappe/heappe-core
$ docker compose --profile sshagent --profile db --profile staging up -d
Check of running containers
$ docker ps

Shutdown Docker containers

Use the code below to shutdown the HEAppE Middleware running containers.
$ cd /opt/heappe/heappe-core
$ docker compose --profile sshagent --profile db --profile staging down
Check if containers are not running
$ docker ps -a

Note

If everything is successfully deployed, HEAppE is available at http://localhost:5000.

Local HPC simulator container is deployed at localhost:49005.