Installation

This guide assumes you have intermediate experience using the Cloud Foundry CLI (Command Line Interface) and operating Cloud Foundry in SAP BTP. If you are unfamiliar to Cloud Foundry, refer to the Cloud Foundry CLI documentation.

The enosix Link application is provided as a Docker container, and deploying it requires configuring a Cloud Foundry manifest YAML file. You will need to configure connectivity, destination, and optionally the XSUAA service.

Additionally, enosix link provides access to your SAP ERP systems via the SAP Cloud Connector, so ensure that SAP Cloud Connector is deployed and configured correctly.

SAP Cloud Foundry account

To deploy the Link application, you'll need an SAP BTP Cloud Foundry Environment. If you're unfamiliar with this environment, please refer to the SAP-provided Getting Started documentation.

note

If you're using a trial account, the application will shut down after a few hours daily. Trial BTP environments are not suitable for production scenarios.

Access SAP BTP - Cloud Foundry

Ensure you have access to the SAP BTP environment via the following links:

Log into the Cloud Foundry Environment using CLI

To log into your SAP BTP Cloud Foundry environment via CLI, follow the SAP guide.
Additional notes:

You can find the API endpoint for your environment under the Cloud Foundry Environment section of the subaccount (Search for API Endpoint:).
Use the cf login --sso option instead of entering a username and password. S-User and Universal passwords can sometimes get out of sync.

Install and Configure SAP Cloud Connector

Refer to the SAP Installation and Configuration documentation for Cloud Connector.

caution

Cloud Connector Security Certificate Expires Annually

The Subaccount certificates in SAP Business Technology Platform expire annually. While renewing them is simple, failure to do so will result in the loss of all connectivity through Cloud Connectors in the subaccount. Refer to the SAP guide on updating the certificate for a subaccount.

Security Details

Please review the Cloud Connector Security Details for more information about how the Cloud Connector enables integration between cloud applications and services within customer networks.

Network Requirements & System Prerequisites

Ensure that your environment meets the necessary Cloud Connector Prerequisites, including supported operating systems, JVM versions, and required network IP addresses.

Configure Cloud Connector for enosix SAP Framework

The Cloud Connector must be configured to enable access from SAP BTP to the connected ERP system running the enosix SAP Framework. This includes creating a Cloud to On-Premise mapping and granting access to the enosix ICF HTTP handler.

Subaccount

Follow the Cloud Connector Access Control guide to set up access.

Steps to add a new system mapping in the subaccount:

Back-end Type: Other SAP System
Protocol: HTTP
Internal Host: DNS name or IP of the SAP ECC/S4 HANA system
Internal Port: e.g., 8000 (HTTP port)
Virtual Host: Create a unique name (e.g., sap-dev)
Virtual Port: 80
Principal Type: None
Host in Request Header: Use Virtual Host
Description: (Optional) Enter the system name.
Summary: Check the checkbox for "Check Internal Host."
Click Finish.

Next, under Resources, add a resource:

URL Path: /enosix/paca
Active: [X]
Access Policy: Path and All Sub-Paths

Validate Exposed System in SAP BTP Cloud Foundary

Once configuration is complete in the SAP Cloud Connector, the exposed back end system will be displayed in the Sub Accounts Cloud Connectors section. Verify the Virtual Host specified previously is shown, without error messages.

Subaccount

Configure Required Services in SAP BTP Cloud Foundry

enosix Link requires the SAP Connectivity Service as a minimum. Additional services like Destinations and Authorization and Trust will unlock more features.
Note: All services are available in SAP BTP Cloud Foundry without additional costs using the lite plan.

Configure the following service instances within the same Cloud Foundry space where Link will be deployed:

Connectivity: Follow the Create and Bind a Connectivity Service Instance guide.
- Plan: lite
- Runtime Environment: Cloud Foundry
- Space: Select the space where Link will be deployed
- Instance Name: connectivity

The space where Link is deployed must have a provisioned connectivity service with the instance name connectivity.

Destination: Refer to the Routing with Destinations section for details. The use of destinations is required to use the advance functionality of link for Principal Propagation and LocationId, it is recommended to configure using destinations over direct routing to cloud connector virtual hosts.
Authorization and Trust: Refer to the Configuring Principal Propagation section for details.

Configure Link Routing

Manifest Template

Use the following manifest.yaml template to deploy Link using Cloud Foundry CLI

There are comments to guide the configuration of each line. <Placeholders> are identified between braces <>

---
applications:
- name: enosix-link-<company-name> # Replace <company-name> with your company name
  random-route: true # Remove this line for production
  memory: 128M # Memory megabytes 128M for dev or qa server 512M or more for production
  docker:
    image: enosix/link:stable # use the stable release channel with auto updates
  services:
   - connectivity # required, ensure the connectivity service is deployed to the target space
   - destination # recommended, use destinations to manage connection to connectivity virtual host's 
  health-check-type: http
  health-check-http-endpoint: /health
  env:
    # Define SAP Server Connection
    Servers__0__Name: sap-dev
    Servers__0__BTP__DestinationName: <destination-name> # Should match the name of the destination configured in BTP Subaccount
    #Servers__0__Proxy__URL: http://<Cloud Connector Virtual Host>:80/enosix/paca # This is a legacy configuration option for directly routing to a connectivity virtual host and not using destinations
    Servers__0__ConcurrentRequests: 10 # Limit the number of concurrent requests to the sap system.
    # Create a Proxy Route to the Server
    Proxies__0__Path: 3de65974f59e200ef27e8ecfb84437f7-proxy-dev # Rename to a unique value, this is the path the proxy route will be available in link once deployed. Suggest appending with a meaningful name using dashes.
    Proxies__0__Server: sap-dev # Should match the name of the Servers__0__Name entry above, this routes this proxy to the defined SAP system and used the configured Destination or Proxy Url. 

Configuration Steps

Copy the manifest.yaml file and create both production and non-production versions.
Replace <company-name> with your company name in lowercase, without spaces.
Remove the random-route line when deploying to a production environment.
Replace <destination-name> with the name of a destination pointing to a cloud connector virtual host.
Customize the Proxy Path 3de65974f59e200ef27e8ecfb84437f7-proxy-dev replace with a value using a guid/uuid generator to create a unique hidden route name. Suggest appending with a meaningful name using dashes.

Deploy to Cloud Foundry and Verify Connectivity

Cloud Foundry Push command

Use the Cloud Foundry CLI and the cf push command to deploy Link from the directory containing your manifest.yaml file. After deployment, the application will be accessible via a Cloud Foundry route.

Note: Only include necessary files in the directory where you execute cf push to avoid uploading extra files.

Sample Output from Cloud Foundary deployment

cf push
Pushing from manifest to org ------ / space dev as ---------...
Using manifest file /Users/mhail/Downloads/link-deploy-test-24/manifest.yaml
Getting app info...

Creating app with these attributes...
+ name:                         enosix-link-test
+ docker image:                 enosix/link:stable
+ health check http endpoint:   /health
+ health check type:            http
+ memory:                       128M
  services:
+   connectivity
+   destination
  env:
+   Proxies__0__Path
+   Proxies__0__Server
+   Servers__0__BTP__DestinationName
+   Servers__0__ConcurrentRequests
+   Servers__0__Name
  routes:
+   enosix-link-...-test-wacky-shark.cfapps.us10.hana.ondemand.com

Creating app enosix-link-...-test...
Mapping routes...
Binding services...

Staging app and tracing logs...
   Cell a7cde4f9-3f4d-466e-9638-ea0cafddf2de creating container for instance 3bac585c-958e-4cfc-a9f6-369bc6b389f5
   Security group rules were updated
   Cell a7cde4f9-3f4d-466e-9638-ea0cafddf2de successfully created container for instance 3bac585c-958e-4cfc-a9f6-369bc6b389f5
   Staging...
   Staging process started ...
   Staging process finished
   Exit status 0
   Staging Complete
   Cell a7cde4f9-3f4d-466e-9638-ea0cafddf2de stopping instance 3bac585c-958e-4cfc-a9f6-369bc6b389f5
   Cell a7cde4f9-3f4d-466e-9638-ea0cafddf2de destroying container for instance 3bac585c-958e-4cfc-a9f6-369bc6b389f5
   Cell a7cde4f9-3f4d-466e-9638-ea0cafddf2de successfully destroyed container for instance 3bac585c-958e-4cfc-a9f6-369bc6b389f5

Waiting for app to start...

name:              enosix-link-test
requested state:   started
routes:            enosix-link-test-wacky-shark.cfapps.us10.hana.ondemand.com
last uploaded:     Thu 19 Sep 16:13:14 EDT 2024
stack:             
docker image:      enosix/link:stable

type:            web
instances:       1/1
memory usage:    128M
start command:   dotnet Link.dll 
     state     since                  cpu    memory   disk     details
#0   running   2024-09-19T20:13:19Z   0.0%   0 of 0   0 of 0   

Routing Explained

In the template above, a Proxy was created to Path 3de65974f59e200ef27e8ecfb84437f7-proxy-dev from the output the Cloud Foundry route is enosix-link-test-wacky-shark.cfapps.us10.hana.ondemand.com. Therefore, the URL to access the defined SAP dev server system will be: https://enosix-link-test-wacky-shark.cfapps.us10.hana.ondemand.com/3de65974f59e200ef27e8ecfb84437f7-proxy-dev.
Request to that Proxy will be sent to the sap-dev Server, that uses a Destination to route to a Virtual Host via the SAP Cloud Connector to access the SAP System.

Health Check

Link will have a degraded state with incorrect or invalid configuration. to view any configuration errors access the /health endpoint. From the configuration above the url https://enosix-link-test-wacky-shark.cfapps.us10.hana.ondemand.com/health will provide the health check and any configuration validation issues. See the Health Enpoint for details and resolving configuration issues.

Testing & Connectivity Verification

Access the route with the token in the URL. You should be prompted for authentication. Test the connection using valid SAP credentials (username and password).

Installation

SAP Cloud Foundry account​

Access SAP BTP - Cloud Foundry​

Log into the Cloud Foundry Environment using CLI​

Install and Configure SAP Cloud Connector​

Cloud Connector Security Certificate Expires Annually​

Security Details​

Network Requirements & System Prerequisites​

Configure Cloud Connector for enosix SAP Framework​

Steps to add a new system mapping in the subaccount:​

Validate Exposed System in SAP BTP Cloud Foundary​

Configure Required Services in SAP BTP Cloud Foundry​

Configure Link Routing​

Manifest Template​

Configuration Steps​

Deploy to Cloud Foundry and Verify Connectivity​

Cloud Foundry Push command​

Sample Output from Cloud Foundary deployment​

Routing Explained​

Health Check​

Testing & Connectivity Verification​