Performing a Manual Deployment

Objectives
After completing this lesson, you will be able to:

After completing this lesson, you will be able to:

  • Perform a manual deployment

Deploy SAP BTP Cloud Foundry Applications Manually: Exercise Overview

Scenario

You will deploy your CAP application into the Cloud Foundry environment of the SAP Business Technology Platform manually using:

  • The Cloud Foundry Command Line Interface (CLI).
  • A Multi-target application (MTA) file. You will also replace the in-memory SQLite database with an SAP HANA Cloud Trial instance to store the application data.

Task Flow

In this exercise, you will perform the following tasks:

  • Prepare your project for SAP HANA Cloud deployment.
  • Set Up HDI container on SAP HANA Cloud instance.
  • Update the project to use SAP HANA.
  • Perform further deployment preparations.
  • Perform a manual deployment using CF CLI tools.
  • Perform a manual deployment using a "Multi Target Application" (MTA) file.
  • Generate an MTA Deployment Descriptor (mta.yaml).

Prerequisites

You have added an external service.

Watching the Simulation and/or Performing the Steps

Note
In this exercise you find a simulation and a list of all steps, displayed in the simulation. Performing the steps below allows you to follow the simulation in your own trial account.

Deploy SAP BTP Cloud Foundry Applications Manually

Task 1: Prepare a Project/Extension for SAP HANA Cloud Deployment

First, you need to set up the SAP HANA Cloud Trial instance in your BTP account.

Note
Please note that screens in the cloud may change. So, the screenshots in this solution may differ slightly from the screens in your training system.

Steps

  1. Set Up SAP HANA Cloud Trial Instance (only on learning.sap.com).

    1. Open your SAP BTP Trial Account Cockpit1.

    2. Enter the subaccount that you are using for this course (for example, the trial subaccount).

    3. Enter the space that you are using for this course (for example, the dev space).

    4. In the navigation on the left, choose SAP HANA Cloud.

    5. Select Create and choose SAP HANA database.

      You will be redirected into SAP HANA Cloud Central for the instance creation. When being asked to authenticate, use your SAP Account user credentials that you used to create your SAP BTP Trial account. You should then see the following dialog:

    6. The Location settings should point to yourtrial org and dev space.

      Use the following settings for the remaining fields:

      KeyValue
      Instance Namehana-cloud-trial
      DescriptionHANA Cloud Trial used for exercises
      Administrator Passwordcreate a password according to the password policy

    7. Click on the Step 2 button.

    8. The default parameters for your trial SAP HANA Cloud database display. Select the Step 3 button.

    9. You will see the SAP HANA Database Advanced Settings dialog. Here, you can allow or deny certain IP addresses for connection to your database instance.

      You also find a setting to connect the database to remote sources via the Cloud Connector. This is especially useful in replication use cases, where you need to replicate data from on-premise sources to your SAP HANA Cloud instance. In our use case, this setting is not required.

    10. Select the Allow all IP addresses option, then select the Step 4 button.

    11. TheData Lake page displays. Accept the default values and select the Step 5 button.

    12. TheData Lake Advanced Settings page displays. Choose theCreate Instance button.

    13. The overview of your database instances appears. There should be a new entry for your hana-cloud-trial instance with StatusCREATING.

      The process will take several minutes to complete. Once done, the Statusshould switch to RUNNING. Use the Refreshbutton to update the status. Your SAP HANA Cloud Trial instance is now ready to be used.

    14. Return to your BTP trial account and select SAP HANA Cloud.

    15. Your hana-cloud-trial instance displays in the SAP HANA Database Instances overview.

Task 2: Set Up HDI Container on SAP HANA Cloud Instance

The SAP HANA Cloud instance serves as your cloud database. You can now create schemas or HDI containers on the database. You can bind a schema or HDI container to an application to create the data schema and store the application data.

Steps

  1. Set Up HDI Container on SAP HANA Cloud Instance.

    1. In your BTP cockpit, select Service Marketplace on the left.

    2. The Service Marketplace displays. Type schemas in the Search field and then select the SAP HANA Schemas & HDI Containers tile.

    3. Select the Create button.

    4. The New Instance or Subscription page appears. Set the Plan to hdi-shared, enter risk-management-db in the Instance Name field, and then select Create.

    5. In the Informationdialog that appears, select Instances and Subscriptions.

    6. Your risk-management-db instance of the SAP HANA Schemas & HDI Containers service appears in the list. This service instance is the database container that the CAP data schema will be deployed to.

Task 3: Update the Project to use SAP HANA

As you want your CAP service to use the newly created SAP HANA Cloud HDI container, you need to update the project.

Steps

  1. Update Project to use SAP HANA.

    1. Run the command cds add hana.

    2. The projects package.json will be updated with the required configurations.

      The following parts are added to the cds section of the file:

      Code snippet
      
      {
          ...
          ... 
          "cds": {
             "requires": {
                ...
                ...
                "db": {
                   "kind": "sql"
                } 
           },
           "hana": {
               "deploy-format": "hdbtable"
           }
         }
      }
      Copy code

      This configures deployment for SAP HANA to use the hdbtable and hdbview formats. They are special file formats that are generated during the build process from the .cds. definition files and can be deployed to SAP HANA Cloud, in order to create the data schema.

Task 4: Perform Further Deployment Preparations

Steps

  1. Perform further deployment preparations.

    1. Go to the SAP BTP Cockpit, subaccount level and select ConnectivityDestinations of the navigational menu on the left side.

    2. Choose New Destination.

    3. Enter the following values into the form:

      KeyValue
      NameAPI_BUSINESS_PARTNER
      TypeHTTP
      DescriptionBusiness Partner Sandbox API
      URLhttps://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER/
      Proxy TypeInternet
      AuthenticationNo Authentication
      Note
      In the URL, there is no blank between opu/ and odata. The line break in the URL is automatically created in this handbook.
    4. When finished, press Save.

    5. The destination needs to be accessed from your CAP service. For that, you need to create a service instance of the destination service and adjust the configuration of your package.json file.

    6. Select Instances and Subscriptions and then select Create.

    7. In the dialog, use the following settings:

      KeyValue
      ServiceDestination
      PlanLite
      Runtime EnvironmentCloud Foundry
      Spaceyour space, for example, dev
      Instance Namerisk-management-destination-service
    8. Select Create. The destination service instance will be created.

      The destination service instance will be created.

    9. Still being in the Instances and Subscriptions section, select Create again.

    10. In the dialog, use the following settings:

      KeyValue
      ServiceAuthorization & Trust Management (xsuaa)
      Planapplication
      Runtime EnvironmentCloud Foundry
      Spaceyour space, for example, dev
      Instance Namerisk-management-xsuaa
    11. Select Next.

      You are required to provide a configuration.

    12. Go to your BAS project and run the following command: cds compile srv/ --to xsuaa > xs-security.json

      This will generate the file xs-security.json in your project root folder.

    13. Open the file and change the xsappname-value to risk-management-<YOURDEVSPACE>:

      Make sure to replace <YOURDEVSPACE> with your dev-space name. It should then look like this for instance:

      "xsappname": "risk-management-dev",
    14. Copy the JSON.

    15. Go back to the SAP BTP Cockpitdialog for the xsuaa instance creation and paste the copied JSON structure.

    16. Select Create.

      An instance of the xsuaa service will be created.

    17. Your Service Instances overview should now look like the following:

Task 5: Perform a Manual Deployment Using CF CLI Tools

Steps

  1. Perform a manual deployment using CF CLI tools.

    1. In the package.json file, in the requires section, add the following code:

      Code snippet
      
      "xsuaa": {
          "kind": "xsuaa"
      }
      Copy code

      The result should look like the following:

      Code snippet
      
      {
        ...
        ...
        "cds": {
              "requires": {
                  "API_BUSINESS_PARTNER": {
                      "kind": "odata",
                      "model": "srv/external/API_BUSINESS_PARTNER",
                      "credentials": {
                          "url": "https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER/"
                      }
                  },
                  "db": {
                      "kind": "sql"
                  },
                  //## BEGIN OF INSERT
                  "xsuaa": {
                      "kind": "xsuaa"
                  }
                  //##END OF INSERT
              },
              "hana": {
                  "deploy-format": "hdbtable"
              }
          }
      }
      Copy code

    2. Run the command cds add cf-manifest to create the deployment manifest files.

      This command creates the files manifest.yml and services-manifest.yml in your project root. You are going to adjust the manifest.yml file in the next steps. The services-manifest.yml file contains the Cloud Foundry services, that are required for your project and are derived from the service bindings in package.json using the cds.requires configuration.

    3. Take a look at the new manifest.yml file in your project root. It shows your application components and their services dependencies (services sections).

    4. For the risk-management-srv application, add the following line into the services section: - risk-management-destination-service

      The resulting risk-management-srv application section should look like the following:

      Code snippet
      
      - name: risk-management-srv
        random-route: true # for development only
        path: gen/srv
        memory: 256M
        buildpack: nodejs_buildpack
        services:
          - risk-management-db
          - risk-management-xsuaa
          - risk-management-destination-service
      Copy code

      You have now defined that your application requires the destination service instance that you created earlier.

    5. In the package.json file in your project root, change the following lines by deleting or inserting code as indicated:

      Code snippet
      
      {
        ...
        ...
        "cds": {
              "requires": {
                  "API_BUSINESS_PARTNER": {
                      "kind": "odata",
                      "model": "srv/external/API_BUSINESS_PARTNER",
                      //### BEGIN OF DELETE
                      "credentials": {
                          "url": "https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER/"
                      },
                      //### END OF DELETE
                      //### BEGIN OF INSERT
                      "[development]": {
                          "credentials": {
                              "url": "https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER/"
                          }
                      },
                      "[production]": {
                          "credentials": {
                              "destination": "API_BUSINESS_PARTNER"
                          }
                      }
                      //### END OF INSERT
                  },
                  "db": {
                      "kind": "sql"
                  },
                  "xsuaa": {
                      "kind": "xsuaa"
                  }
              },
              "hana": {
                  "deploy-format": "hdbtable"
              }
          }
      }
      Copy code

      Here you tell the service to distinguish between the development and the production scenarios. When in development, the API URL is retrieved directly from the package.json. In a production scenario, the URL should be retrieved from a destination called API_BUSINESS_PARTNER.

    6. Run the command cds build --production to generate the source files required for production deployment.

    7. Run the command cf login to login to the CF environment.

    8. Use the API-endpoint from the BTP cockpit. Use your user and password and select the org and space where you want to deploy the application to.

    9. Run the command cf push within the root folder of your BAS project.

      The database module and the service module defined in the manifest.yml will be deployed into your CF account.

      The deployment takes a while. You can follow the deployment activity in the terminal log.

      Note
      There also exists the command cf create-service-push, which additionally to the deployment of the the application modules in manifest.yml creates or updates the service instances of the services defined in the services-manifest.yml file. In this case, as you have created the required service instances manually before, you do not need to use the command.
    10. When the deployment is complete, check the logs for a section where module risk-management-srv is being started. Within that section, you find a route, which represents the service URL:

      This is the URL for your CAP service that was generated during the deployment. Your service is running on the SAP Business Technology Platform and is publicly available via the Internet using this URL.

    11. Copy the URL from your deployment log and open it in a new browser tab.

    12. Try to open the BusinessPartners endpoint.

      It should result in an error. The reason is that your service currently cannot access the SAP API Business Hub sandbox environment because it is missing the API key. Previously, during local testing, you provided it via the .env file. This is inaccessible in the BTP environment.

    13. You must set the API key as an environment variable apikey for the productive Cloud Foundry environment. You need to do this manually and just once, by running the following command in your terminal:cf set-env risk-management-srv apikey <your-api-key>.

      Make sure, that you replace <your-api-key> with your API key from the API Business Hub.

      With the following command:cf env risk-management-srv you can also verify that the key has been set as user-provided variable.

    14. Run the following command: cf restart risk-management-srv

      This ensures that your environment variable change takes effect in the application.

    15. Open the browser tab with the running service. The BusinessPartners endpoint should now provide the data from the external service, the SAP API Business Hub sandbox environment.

      Try to open the other service endpoints. The corresponding data should appear. Just now, it is not stored in an SQLite database, but in your SAP HANA Cloud HDI Container.

      You will notice, that the web application (the UI part) is missing. This was left out on purpose. You are going to add it to your BTP deployment in a later step, because it requires an additional component, the so-called application router.

Task 6: Perform a Manual Deployment Using a "Multi Target Application" (MTA) File

In this section, we will create a "Multi Target Application" (MTA) file for deployment. (See the description2). MTA is a way to create deployments consisting of multiple modules that can be implemented in different technologies. Some advantages of this technology are:

  • It provides a build tool.
  • It creates service instances, service keys, and destinations automatically.
  • It deploys content (HTML5, workflow, …).
  • It supports blue-green deployment3.

Compared to the deployment procedure you performed in the previous steps, this will save you a lot of manual work in the long run.

Task 7: Generate an MTA Deployment Descriptor (mta.yaml)

The MTA deployment is described in the MTA Deployment Descriptor4, a file called mta.yaml. In the first step, let CAP generate an initial mta.yaml file.

Steps

  1. Generate an MTA deployment descriptor (mta.yaml).

    1. Open a new terminal in BAS (TerminalNew Terminal).

    2. Run the following command cds add mta in the terminal.

      The cds Command Line Interface has generated the mta.yaml file based on your previously created settings in the package.jsonfile.

    3. Open the new mta.yaml file.

      The mta.yaml file consists of different modules, that are Cloud Foundry apps, and resources, that are Cloud Foundry services.

      Modules:

      • risk-management-srv - Your CAP OData service.
      • risk-management-db-deployer - Deploys CAP schema and data (CSV files) to database.

      Resources:

      The resources are generated from the requires section of cds in the package.json:

      • risk-management-db - HANA DB HDI container service instance.
      • risk-management-xsuaa - Authorization & Trust Management (xsuaa) service instance.

      The resources are Cloud Foundry service instances, that are automatically created and updated during the MTA deployment.

    4. The risk-management-xsuaa service instance should make use of the xs-security.json configuration file you generated in an earlier step. Add the following line to the parameters section of the risk-management-xsuaa resource in the mta.yaml file:

      path: ./xs-security.json

      Also remove the config section, as you are providing the configuration via the xs-security.json file.

      The result should look like the following:

      Code snippet
      
      # ------------------------------------------------------------
      - name: risk-management-xsuaa
        # ------------------------------------------------------------
        type: org.cloudfoundry.managed-service
        parameters:
          service: xsuaa
          service-plan: application
          path: ./xs-security.json # this line was added
      Copy code

      The line type: org.cloudfoundry.managed-service tells the MTA deployment to automatically create the service instance if it does not yet exist. The service and service-plan parameters tell the MTA deployment what kind of service instance to create. As you have created the service instance manually before, it will just be updated with the provided configurations during MTA deployment.

    5. The dependency to the destination service instance is still missing in the mta.yaml. We need to add it manually. As the risk-management-srv module requires the destination service, add the following line into its requires section:

      Code snippet
      - name: risk-management-destination-service
      Copy code
      The result should look like the following:
      Code snippet
      # --------------------- SERVER MODULE ------------------------
      - name: risk-management-srv
        # ------------------------------------------------------------
        type: nodejs
        path: gen/srv
        requires:
          # Resources extracted from CAP configuration
          - name: risk-management-db
          - name: risk-management-xsuaa
          - name: risk-management-destination-service # this line was added
        provides:
          - name: srv-api # required by consumers of CAP services (e.g. approuter)
            properties:
              srv-url: ${default-url}
      Copy code

    6. When adding a requirement, this also needs to be defined in the resources section of the document.

      Add the following lines in the resources section:

      Code snippet
      # ------------------------------------------------------------
      - name: risk-management-destination-service
        # ------------------------------------------------------------
        type: org.cloudfoundry.managed-service
        parameters:
          service: destination
          service-plan: lite
      Copy code

    7. Save the file.

    8. Run the following command of the MTA build tool in order to build your project: mbt build -t ./

      The build takes a while. It results in a multitarget application archive file, ending with the .mtar file extension.

    9. Before running the following command, ensure that the SAP HANA database is still running: cf deploy <.mtar file>

      Replace <.mtar file> with the file name of the generated archive. In this case cf deploy risk-management_1.0.0.mtar.

      The deployment takes a while. You can follow the deployment activity in the terminal log.

    10. At the end of the deployment log, you will find a line saying: Application "risk-management-srv" started and available at "<some_URL>".

      Like in this screenshot:

      This is the application URL for your CAP service, which is publicly available via the Internet. Now this might not seem like a big win, because we are achieving the same deployment result as with the previous manual deployment. But the MTA deployment offers some more advantages:

      • A build tool
      • Automatically created service instances
      • Service keys
      • Destinations
      • Content deployment (HTML5, workflow, …)
      • Blue-green deployment

Result

You have:

  • Created an application.
  • Created a UI with SAP Fiori elements.
  • Added custom business logic.
  • Added an external service.
  • Deployed your application manually.

You still have to deploy the UI part of your application. For this deployment, you will need an application router (approuter). To manage the access to your application, you need to implement restrictions and roles. We will cover all this in the next part.

Reference Links Performing a Manual Deployment

For your convenience this section contains the external references in this lesson.

If links are used multiple times within the text, only the first location is mentioned in the reference table.

Reference Links: Manual Deployment

Ref#SectionContext text fragmentBrief descriptionLink
1Set Up SAP HANA Cloud Trial InstanceOpen your SAP BTP Trial Account CockpitOpen SAP BTP cockpithttps://cockpit.hanatrial.ondemand.com/trial/#/globalaccount
2Manual Deployment Using a "Multi Target Application" (MTA) File(MTA) file for deploymentSAP Help Portal, Create the MTA...https://help.sap.com/viewer/4505d0bdaf4948449b7f7379d24d0f0d/2.0.05/en-US/ebb42efc880c4276a5f2294063fae0c3.html
3Manual Deployment Using a "Multi Target Application" (MTA) Fileit supports blue-green deployment.SAP Help Portal, Blue-Green Deployment Strategyhttps://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/7c83810c31d842938cbc39c135a2d99f.html
4Generate MTA Deployment Descriptor (mta.yaml)MTA deployment is described in the MTA Deployment DescriptorSAP Help Portal, MTA deploymenthttps://help.sap.com/viewer/4505d0bdaf4948449b7f7379d24d0f0d/2.0.03/en-US/33548a721e6548688605049792d55295.html

Save progress to your learning plan by logging in or creating an account