Hermes for S4/Hana

Introduction

Hermes is an open-source middleware in order to sync vendor master data between Graphite Connect and on-premise ERPs. Hermes supports an interface to SAP S4/HANA, and has the ability to create and update business partners and populate address, banking, company code and purchasing organization data.

Choosing an Installation Method

Use the native installer or package for single-instance deployments. Choose the ZIP method to run multiple independent Hermes instances on a single machine or to deploy to environments without a package manager.

System Requirements

• OS:
  • Windows 10 / Windows Server 2019 or later (x64)
  • Any recent x64 Linux distribution with glibc >= 2.28
• Memory: 500 MB available RAM
• Disk: 1 GB (300 MB for installation, remainder for logs)
• CPU: Any modern x64 CPU
• Windows only: Microsoft Visual C++ Redistributable 2013 is required by the bundled node-rfc dependency

Windows — Native Installer (.exe)

This is the recommended method for Windows users running a single Hermes instance.

Installation

1. Download the latest Hermes Windows installer:

   • Production: Hermes-Windows-Installer.exe
   • Testing/development: Hermes-Windows-Installer.exe

2. Right-click the installer and select Run as administrator.

3. Run the installation wizard. Accept the license agreement and choose an installation directory (the default is C:\Program Files\Graphite Hermes\).

4. Once the wizard completes, the installer creates a production.json configuration file in the installation directory. Open it in a text editor and fill in your environment-specific settings. See Configuration.

5. Open Windows Services (services.msc), locate Graphite Hermes, and start it.

Uninstalling

Open Add or Remove Programs, find Graphite Hermes, and click Uninstall. This stops the service and removes all application files.

Updating

1. Download the latest installer from the links above.

2. Right-click and select Run as administrator.

When you run the new installer, it detects your existing installation, stops the running service, replaces the application files, and restarts the service. Your production.json remains unchanged.

Windows — ZIP Installation

Use this method to run multiple Hermes instances on the same Windows machine — for example, one instance per SAP system or environment. Each instance lives in its own directory and registers as a separate Windows service.

Installation

1. Download the latest Hermes Windows ZIP:

   • Production: hermes.windows.zip
   • Testing/development: hermes.windows.zip

2. Extract the ZIP to the directory where you want this instance to live, for example C:\hermes-primary\. For a second instance, extract to a separate directory such as C:\hermes-secondary\.

3. Open production.json in the extracted directory and fill in your environment-specific settings. If it does not exist yet, create it from production.example.json first. See Configuration.

   cmd

   copy /Y "C:\hermes-primary\production.example.json" "C:\hermes-primary\production.json"

4. To register the instance as a Windows service, right-click Command Prompt and select Run as administrator, then run install.cmd from the instance directory:

   cmd

   "C:\hermes-primary\install.cmd"

   The script prompts you for a unique service name. This name identifies the service in Windows Services and is saved into production.json as windowsServiceName.

5. Open Windows Services (services.msc), locate your named service, and start it.

Note: Each instance must have a unique service name so that Windows can manage them independently. If two instances share the same name, Windows overwrites the first service definition, causing one instance to stop working. Use a descriptive name for each instance (e.g., Hermes-Primary, Hermes-Secondary).

Uninstallation

1. From an administrator Command Prompt, uninstall the service. The service name is the one you entered during installation, and can also be found in production.json as windowsServiceName:

   cmd

   "C:\hermes-primary\node.exe" "C:\hermes-primary\dist\win-svc.js" uninstall --name "Your Service Name"

2. Once the service is uninstalled, delete the instance directory:

   cmd

   rmdir /s /q "C:\hermes-primary"

Updating

Run the self-updater from an administrator Command Prompt:

"C:\hermes-primary\node.exe" "C:\hermes-primary\dist\update.js" <build>

Replace <build> with release for production or develop for testing/development.

This command stops the service, downloads the latest build, applies it, and restarts the service. Your production.json remains unchanged.

Linux — Native Package (.deb / .rpm)

This is the recommended method for Linux users running a single Hermes instance. It installs Hermes to /opt/graphite-hermes/ and registers a systemd service that runs under a dedicated hermes system user.

Post-install checklist (Linux package)

Run this checklist after installing either the .deb or .rpm package:

1. Configure /opt/graphite-hermes/production.json.
2. Start Hermes manually:
   Bash

   sudo systemctl start graphite-hermes

3. Verify service status:
   Bash

   sudo systemctl status graphite-hermes

Expected behavior: On first install, the package enables graphite-hermes at boot but does not start it. Hermes requires a valid production.json before it can connect to SAP and Graphite. Start the service manually after completing your configuration.

Installation — Debian / Ubuntu (.deb)

1. Download the latest Hermes .deb package:

   • Production: hermes.linux.deb
   • Testing/development: hermes.linux.deb

2. Install the package:

   Bash

   sudo apt-get install -y /path/to/hermes.linux.deb

3. Follow the Post-install checklist (Linux package).

Installation — Red Hat / Rocky Linux / Amazon Linux (.rpm)

1. Download the latest Hermes .rpm package:

   • Production: hermes.linux.rpm
   • Testing/development: hermes.linux.rpm

2. Install the package:

   Bash

   sudo rpm -i /path/to/hermes.linux.rpm

3. Follow the Post-install checklist (Linux package).

Uninstallation

Debian / Ubuntu:

sudo apt-get remove -y graphite-hermes   # uninstalls the graphite-hermes package

Red Hat / Rocky Linux / Amazon Linux:

sudo rpm -e graphite-hermes   # uninstalls the graphite-hermes package

Note: During uninstallation, the package manager copies your production.json configuration file to /opt/graphite-hermes-production.json.bak. You can use this backup to restore your settings if you reinstall later.

Updating

1. Download the latest package from the links above.

2. Debian / Ubuntu:

   Bash

   sudo apt-get install -y /path/to/hermes.linux.deb

   Red Hat / Rocky Linux / Amazon Linux:

   Bash

   sudo rpm -U /path/to/hermes.linux.rpm

This command stops the service, replaces the application files, and restarts the service. Your production.json remains unchanged.

Linux — ZIP Installation

Use this method to run multiple Hermes instances on the same Linux machine (for example, one instance per SAP system) or to deploy to minimal environments that do not include apt or rpm. Store each instance in its own directory and register it as a separate systemd service.

Post-install checklist (Linux ZIP)

Run this checklist after extracting and registering each ZIP instance:

1. Configure /opt/<your-instance>/production.json.
2. Start the instance manually:
   Bash

   sudo systemctl start <service-name>

3. Verify service status:
   Bash

   sudo systemctl status <service-name>

Expected behavior: install.sh enables <service-name> at boot but does not start the service. Hermes requires a valid production.json before it can run.

Installation

1. Download the latest Hermes Linux ZIP:

   • Production: hermes.linux.zip
   • Testing/development: hermes.linux.zip

2. Extract the ZIP to the directory where you want this instance to live:

   Bash

   sudo mkdir -p /opt/graphite-hermes-primary
   sudo unzip /path/to/hermes.linux.zip -d /opt/graphite-hermes-primary

   For a second instance, extract to a separate directory:

   Bash

   sudo mkdir -p /opt/graphite-hermes-secondary
   sudo unzip /path/to/hermes.linux.zip -d /opt/graphite-hermes-secondary

3. Open production.json in a text editor and fill in your environment-specific settings. If it does not exist yet, create it from production.example.json first. See Configuration.

   Bash

   sudo cp /opt/graphite-hermes-primary/production.example.json /opt/graphite-hermes-primary/production.json
   sudo nano /opt/graphite-hermes-primary/production.json

4. Register the instance as a systemd service by running install.sh from the instance directory:

   Bash

   sudo /opt/graphite-hermes-primary/install.sh

   When you run the script, it prompts you for a unique service name and creates a systemd unit file at /etc/systemd/system/<service-name>.service scoped to that directory.

5. Follow the Post-install checklist (Linux ZIP).

Note: Each instance must have a unique service name so that systemd can manage them independently. If two instances share the same name, the second registration overwrites the first unit file, causing one instance to stop working. Use a descriptive name for each instance (e.g., graphite-hermes-primary, graphite-hermes-secondary).

Note: systemd runs the service as the user who invoked install.sh via sudo, inheriting that user's file-system and network permissions. The service can only access files and network resources that the invoking user has permission to reach. To run the service as a different user, edit the User= line in the unit file at /etc/systemd/system/<service-name>.service before starting the service.

Uninstalling (Linux ZIP)

sudo systemctl stop <service-name>
sudo systemctl disable <service-name>
sudo rm /etc/systemd/system/<service-name>.service
sudo systemctl daemon-reload
sudo rm -rf /opt/graphite-hermes-primary

Updating

Run the self-updater from within the instance directory:

sudo /opt/graphite-hermes-primary/node /opt/graphite-hermes-primary/dist/update.js <build>

Replace <build> with release for production or develop for testing/development.

When you run this command, it stops the service, downloads the latest build, applies the update, and restarts the service. Your production.json remains unchanged.

Configuration

After installation, open production.json in the Hermes installation directory and update it with your environment-specific settings before starting the service. The installer automatically creates this file from production.example.json on first install.

{
  "graphiteApiUrl": "API Endpoint from which Hermes will request data from Graphite",
  "graphiteApiKey": "Graphite API Key",
  "graphiteInterfaceName": "Hermes Interface Name",
  "adapterType": "Hermes adapter type (Will always be 'SAP_S4')",
  "S4Params": {
    "baseUrl": "URL to access the business partner endpoint on S4",
    "bankBaseUrl": "URL to access to bank master endpoint on S4",
    "username": "Integration Username",
    "password": "Integration User Password",
    "client": "S4 Client Number"
  }
}

The production.json file might look like:

{
  "graphiteApiUrl": "https://poc-api.projectgraphite.com",
  "graphiteApiKey": "US12345.0123456789abc.0123456789abcdefg0123456789abcdefg",
  "graphiteInterfaceName": "SFour",
  "adapterType": "SAP_S4",
  "S4Params": {
    "baseUrl": "https://my123456.s4hana.cloud.sap/sap/opu/odata/sap/API_BUSINESS_PARTNER",
    "bankBaseUrl": "https://my123456.s4hana.cloud.sap/sap/opu/odata4/sap/api_bank/srvd_a2x/sap/bank/0001",
    "username": "GRAPHITE_USER",
    "password": "aVery$trongPassword54321%",
    "client": "500"
  }
}

Note: Ensure production.json contains valid JSON. Restart Hermes for any configuration changes to take effect.

For information on generating a Graphite API key, see the Graphite Connect help center.

For information on encrypting the configuration file to protect sensitive credentials, see the Encryption section.

Update notifications (native and ZIP installs)

Hermes can check for new builds in the background and log a warning when an update is available. This check is notification-only and does not auto-install updates.

After each check, Hermes also writes the latest check result to update-status.json in the Hermes installation directory.

Supported production.json settings:

{
  "updateCheckEnabled": true,
  "updateChannel": "release",
  "updateCheckIntervalHours": 24,
  "updateNotifyCooldownHours": 24,
  "updateCheckTimeoutMs": 3000
}

• updateCheckEnabled: enable/disable background update checks.
• updateChannel: release or develop.
• updateCheckIntervalHours: how often Hermes checks for updates.
• updateNotifyCooldownHours: minimum time before repeating the same update warning.
• updateCheckTimeoutMs: HTTP timeout for the update check.

Note: For production environments, keep updateChannel set to release.

Note: Changes to these settings are loaded at process start. Restart the Hermes service after editing production.json.

Updating Hermes

Replace <build> with release for production or develop for testing/development. For native installers and packages, download from the corresponding build link in the installation sections above.

Migrating from a Previous Installation

Existing ZIP users moving to the native installer or package (single instance)

If you were previously running Hermes from a ZIP and want to switch to the native installer or package:

1. Back up your configuration:

   Bash

   # Linux
   cp /path/to/hermes/production.json ~/production.json.bak

   On Windows, copy production.json from the Hermes directory to a safe location.

2. Stop and uninstall the old service:

   Linux (systemd):

   Bash

   sudo systemctl stop <your-service-name>
   sudo systemctl disable <your-service-name>
   sudo rm /etc/systemd/system/<your-service-name>.service
   sudo systemctl daemon-reload

   Windows (administrator Command Prompt):

   cmd

   "C:\path\to\hermes\node.exe" "C:\path\to\hermes\dist\win-svc.js" uninstall --name "Your Service Name"

3. Download the latest ZIP for your platform:

   • Linux (release): hermes.linux.zip
   • Linux (develop): hermes.linux.zip
   • Windows (release): hermes.windows.zip
   • Windows (develop): hermes.windows.zip

4. Restore your configuration by copying your backed-up production.json over the new one:

   Bash

   # Linux
   sudo unzip -o /path/to/hermes.linux.zip -d /opt/your-hermes-instance

   On Windows, copy the backed-up file to C:\Program Files\Graphite Hermes\production.json.

5. Start the service.

Existing ZIP users staying on ZIP (multiple instances)

If you are running multiple instances, do not use the native package — it installs a single shared instance to /opt/graphite-hermes/ and will not be aware of your existing custom service definitions.

The update script (update.js) changed significantly in recent versions of Hermes. For existing ZIP installations on older versions, perform a fresh installation per instance rather than running the updater. This approach gives you a clean, known-good state. Once you migrate each instance to the current ZIP layout, use the normal ZIP update flow described in Updating Hermes.

For each instance:

1. Back up your configuration and systemd unit file (Linux) before making any changes:

   Bash

   cp /opt/your-hermes-instance/production.json ~/production-instance.json.bak
   cp /etc/systemd/system/<your-service-name>.service ~/your-service-name.service.bak

   On Windows, copy production.json from the instance directory to a safe location.

2. Stop and disable the existing service:

   Linux:

   Bash

   sudo systemctl stop <your-service-name>
   sudo systemctl disable <your-service-name>

   Windows (administrator Command Prompt):

   cmd

   "C:\path\to\hermes-instance\node.exe" "C:\path\to\hermes-instance\dist\win-svc.js" uninstall --name "Your Service Name"

3. Download the latest ZIP for your platform:

   • Linux: hermes.linux.zip
   • Windows: hermes.win32.zip

4. Extract the new ZIP over the existing instance directory, replacing all application files:

   Linux:

   Bash

   sudo unzip -o hermes.linux.zip -d /opt/your-hermes-instance

   Windows: Extract the ZIP contents into the existing instance folder, choosing to overwrite all files when prompted.

5. Restore your production.json from the backup you made in step 1, because extracting the ZIP may have overwritten it with the example file:

   Linux:

   Bash

   sudo cp ~/production-instance.json.bak /opt/your-hermes-instance/production.json

   On Windows, copy the backed-up file back into the instance directory.

6. Re-register the service:

   Linux — run install.sh and enter the same service name as before when prompted:

   Bash

   sudo /opt/your-hermes-instance/install.sh

   Important (Linux): If your previous systemd unit file contained custom Environment= entries (for example, self-signed certificate paths or a custom LD_LIBRARY_PATH), re-apply those entries to the new unit file at /etc/systemd/system/<service-name>.service before starting the service. Refer to your backup from step 1 to identify which entries to re-add.

   Windows — run install.cmd and enter the same service name as before when prompted:

   cmd

   "C:\path\to\hermes-instance\install.cmd"

7. Start the service:

   Linux:

   Bash

   sudo systemctl start <your-service-name>

   Windows: Open Windows Services (services.msc), locate your service, and start it.

8. Repeat for each instance using its own directory and service name.

Encryption

Hermes requires a key in order to decrypt the configuration file. You can supply this key to Hermes in several ways:

• An environment variable (HERMES_ENCRYPTION_KEY)
  • This option allows Hermes to start as a service without user interaction.
• An interactive CLI program
  • This option requires users to run a CLI command every time hermes restarts, prompting that user for the encryption key. The CLI will send the key to the running Hermes process which can then decrypt the configuration file and continue operation. If the configuration file is encrypted, Hermes will block until it receives the key.

CLI Usage

Configuration settings can be secured by symmetrically encrypting them with a password. Hermes comes with a CLI to help facilitate this process. To Encrypt, run the commands from the top directory:

• Windows: node.exe dist\encryption.js --encrypt
• Linux: node dist/encryption.js --encrypt

The CLI will then prompt the user for a password. Once entered, the contents of production.json will be encrypted and moved into the production.json.encrypted file. One must keep a copy of this password elsewhere, as there is no way to recover this password if it is lost. If the password is lost, the contents of production.json.encrypted will be unrecoverable, and it will have to be recreated.

Hermes uses the AES-256 CTR cipher for encryption.

Starting Hermes with an Encrypted Configuration

The process for starting Hermes using an encrypted config file is slightly different than the standard usage. After the initial step of starting Hermes via the command/shell script or as a windows service, Hermes will await a separate command to be provided the password with which it will decrypt in memory the configuration settings. To do so, run the command in a separate terminal:

• Windows: node.exe dist\encryption.js --provide `
• Linux: node dist/encryption.js --provide

The CLI will prompt the user for a password. The password that is entered must be the same password that was used to encrypt the file with. Otherwise, the decryption will not be successful.

Decryption

To make edits to or view the contents of production.json.encrypted, run the command:

• Windows: node.exe dist\encryption.js --decrypt
• Linux: node dist/encryption.js --decrypt

The CLI will prompt the user for the password used for the encryption. If successful, contents will be written out to the prouction.json file. Otherwise, an error will be thrown and the command will have to be run again with the correct password.

Windows Service

To run Hermes as a Windows Service, run the following command with admin privledges:

node.exe dist\win-svc.js install

This will install a service (named "Graphite Hermes" by default) and start it. The name of the service can be configured using the windowsServiceName parameter in the production.json file.

To uninstall, run with admin privileges:

node.exe dist\win-svc.js uninstall