Deploying to Cloud Foundry

    Towards SAP Business Technology Platform

    CAP applications can be deployed to the Cloud Foundry environment of SAP BTP. At the end, it’s about deploying regular Node.js and/or Java applications, and about creating and binding appropriate service instances. See the Cloud Foundry Developer Guide for more details.

    The following sections are a continuation of the Getting Started in a Nutshell tutorial.


    cf login  # this will ask you to select CF API, org, and space

    When logging in to Cloud Foundry, you were asked to enter the API endpoint. The exact URL of this API endpoint depends on the region of your subaccount. It can be retrieved from the subaccount details of the SAP BTP Cockpit. For example the trial landscape in Europe (Frankfurt) has this endpoint:

    Got errors? See the troubleshooting guide.

    Enhance Project Configuration for SAP HANA

    When continuing the Getting Started in a Nutshell tutorial, it’s now time to switch to SAP HANA as a database. See the SAP HANA section for how to do this.

    Run cds build

    This prepares everything for deployment, and – by default – writes the build output, that is the deployment artifacts, to folder ./gen in your project root.

    Learn how cds build can be configured.

    Deploy Using MTA

    For clean, production-like (pipeline) builds and deployments, we enhance our application to become a Multitarget Application (MTA). The MTA build tool creates a self-contained MTA archive, packaging the different parts of the application (database, service, and UI).

    CAP provides a tool to generate an MTA descriptor mta.yaml out of your CAP project. You can extend generated descriptors with your own MTA extension descriptors if necessary.

    1. Download and install the MTA plugin for the CF CLI.

    2. Install the MTA Build Tool:
      npm install -g mbt

      You might need to install more things (for example, GNU Make on Windows), to let the MTA Build Tool run. Consider the installation section of the MTA Build Tool guide.

    3. To have the MTA development descriptor mta.yaml created in the project root folder, execute
      cds add mta

      For deployment to trial landscapes, replace the service type hana by hanatrial for the resource in mta.yaml.

    4. Run the MTA Build Tool through:
      mbt build -t ./

      An archive with extension .mtar is created in project root.

      If you omit the -t ./ from the mbt build command, the archive is located in the default folder, see the Cloud MTA Build Tool documentation. This deviation isn’t part of the following steps.

    5. Log in to your Cloud Foundry space.
    6. Deploy to Cloud Foundry with:
      cf deploy <.mtar file>  # for example, bookshop_1.0.0.mtar

      This can take some minutes.

    7. Identify the URL of the application, for example bookshop-srv, in the Cloud Foundry space using cf apps. You could also watch the cf deploy log output, or use the SAP BTP Cockpit. Open this URL in your browser.

    Got errors? See the troubleshooting guide.

    Reducing MTA Size During Development

    MTA files may reach considerable size due to the node_modules folder being included. If you use MTAs during development, you may omit that folder from the archive, provided that all your dependencies are available on the public registry

    To do that, first add a file bookshop.mtaext with this content:

    _schema-version: '3.1'
    ID: bookshop-small
    extends: bookshop
     - name: bookshop-srv
         ignore: ["node_modules/"]

    Then rebuild with:

    mbt build -e bookshop.mtaext -t ./

    This speeds up the build significantly as there is less content that is packaged. Since the archive is smaller the upload (cf deploy) is also much faster compared to an archive containing the node_modules folder.

    Deploy Using Manifest Files

    As an alternative to MTA-based deployment, CAP also supports Cloud Foundry native deployment using cf push or cf create-service-push, which creates services and pushes the applications with a single CLI command.

    Install the Create-Service-Push Plugin

    cf install-plugin Create-Service-Push

    This plugin acts the same way as cf push, but extends it such that services are created first. With the plain cf push command, this is not possible.

    Create the Deployment Descriptors

    cds add cf-manifest

    This creates two files, a manifest.yml and services-manifest.yml in the project root folder.

    • manifest.yml holds the applications. In the default layout, one application is the actual server holding the service implementations, and the other one is a ‘DB deployer’ application, whose sole purpose is to start the SAP HANA deployment.
    • services-manifest.yml defines which CF services shall be created. The services are derived from the service bindings in package.json using the cds.requires configuration.

    On trial landscapes, if you’re not using SAP HANA Cloud, replace the broker type hana by hanatrial in services-manifest.yml.

    Unlike the files in the gen folders, these manifest files are genuine sources and should be added to the source control system. This way, you can adjust them to your needs as you evolve your application.

    Build the Project

    cds build --production

    The --production parameter ensures that the cloud deployment related artifacts are created by cds build. See section SAP HANA database deployment for more details.

    The step cds build also generates a manifest.yml file in the build staging folder. This file is redundant and will be removed in a future version.

    Push the Application

    cf create-service-push  # or `cf cspush` in short from 1.3.2 onwards

    This creates service instances, pushes the applications and bind the services to the application with a single call.

    During deployment, the plugin reads the services-manifest.yml file and creates the services listed there. It then reads manifest.yml, pushes the applications defined there, and binds these applications to service instances created before. If the service instances already exist, only the cf push operation will be executed.

    You can also apply some shortcuts:

    • Use cf push directly to deploy either all applications, or cf push <app-name> to deploy a single application.
    • Use cf create-service-push --no-push to only create or update service related data without pushing the applications.

    In the deploy log, find the application URL in the routes line at the end:

    name:              bookshop-srv
    requested state:   started

    Open this URL in the browser and try out the provided links, for example, .../browse/Books. Application data is fetched from SAP HANA.

    To ensure that SAP HANA deployment was successful, check the deployment logs of the database deployer application (cf logs <app-name>-db-deployer --recent). The application itself is by default in state started after HDI deployment has finished, even if the HDI deployer returned an error. To save resources, you can explicitly stop the deployer application afterwards.

    The SAP Fiori Preview, that you are used to see from local development, is only available for the development profile and not available in this scenario. For productive applications, you should add a proper SAP Fiori application

    Multitenant applications are not supported yet as multitenancy-related settings are not added to the generated descriptors. The data has to be entered manually.

    Got errors? See the troubleshooting guide.

    Deploy using CI/CD Pipeline

    We recommend setting up continuous integration and delivery (CI/CD) pipelines for your CAP projects to speed up your development and delivery cycles. SAP offers you two solutions that help you apply CI/CD in your software development. You can choose either way, depending on your requirements and expertise.

    Learn more about SAP Solutions for Continuous Integration and Delivery.

    Managed SAP Continuous Integration and Delivery Service on SAP BTP

    SAP Continuous Integration and Delivery is a service on SAP BTP, which lets you configure and run predefined continuous integration and delivery pipelines. It connects with your Git SCM repository and in its user interface, you can easily monitor the status of your builds and detect errors as soon as possible, which helps you prevent integration problems before completing your development.

    SAP Continuous Integration and Delivery has a ready-to-use pipeline for CAP, that is applicable to Node.js, Java and multitarget application (MTA) based projects. It does not require you to host your own Jenkins instance and it provides an easy, UI-guided way to configure your pipelines.

    Try the tutorial Configure and Run a Predefined SAP Continuous Integration and Delivery (CI/CD) Pipeline to configure a CI/CD pipeline that builds, tests, and deploys your code changes.

    Learn more about SAP Continuous Integration and Delivery.

    Project “Piper”

    Project “Piper” is a solution for continuous integration and delivery that offers the flexibility to set up and extend fully customized pipelines. It is an open-source project that provides preconfigured Jenkins pipelines, which you can use in your own Jenkins master infrastructure and adapt according to your needs. It consists of:

    • A shared library, which contains the description of steps, scenarios, and utilities that are required to use Jenkins pipelines
    • A set of Docker images that can be used out-of-the-box to implement best practice processes

    Try the tutorial Add Automated System Tests for CAP-Based Projects to Your CI/CD Pipeline to create system tests against a CAP-based sample application and automate your tests through a CI/CD pipeline.

    How to Continue

    You might now:

    Learn More

    Build Configuration

    cds build executes build tasks on your project folders to prepare them for deployment. Build tasks compile source files (typically CDS sources) and create the required artifacts, for example, EDMX files, SAP HANA design-time artifacts, etc. All well-known root folders (db, srv, and app) or those configured in the build tasks are built.

    By default, cds build derives build tasks from the project contents:

    • A hana build task is created if an SAP HANA service binding is defined.
    • A node-cf build task for projects using the Nodejs runtime.
    • A java-cf build task for projects using the CAP Java SDK.
    • A mtx build task for multitenancy projects using the Node.js runtime. For Java projects, a mtx build task has to be configured manually as it is not created by default.

    To control which tasks cds build executes, you may want to add them as part of your project configuration in package.json or .cdsrc.json.

    The following build tasks are a default configuration used for Node.js projects:

      "build": {
        "target": "gen",
        "tasks": [
          {"for":"hana",    "src":"db",  "options": {"model": ["db","srv"] }},
          {"for":"node-cf", "src":"srv", "options": {"model": ["db","srv"] }}

    The executed build tasks are logged to the command line. You can use them as a blue print – copy & paste them into your CDS configuration and adapt them to your needs. See also the command line help for further details cds build --help.

    Target Folder is the general folder where the build output is written to. It’s resolved based on the application root folder.

    • For Node.js projects, the "gen" folder below the application root is used by default. All source files are copied to it by cds build, which makes it a self-contained folder that is ready for deployment.
    • For Java projects, the symbolic "." folder is used by default, which means that the build output is stored below the individual source folders. For example, db/src/gen would contain the build output of the default db folder. No source files are copied to db/src/gen because they’re assumed to be deployed from the db folder itself.

    Build Task Properties

    • for: Target technology for which the build is executed. Currently supported types are:
      • node-cf: Creates a deployment layout for Node.js apps on Cloud Foundry.
      • java-cf: Creates a deployment layout for Java apps on Cloud Foundry.
      • hana: Creates a deployment layout for SAP HANA HDI.
      • mtx: Creates a deployment layout for multitenant applications.
      • fiori: Creates a deployment layout for SAP Fiori.
    • src: Source folder of the module that is about to be build.
    • dest: Optional destination of the modules builds, relative to the enclosing project. The src folder is used by default.
    • options: Sets technology-specific options according to the target technology. The target technologies node-cf, java-cf, and hana support the option model, which can be either of type string or string array. The cds build uses the given folders or .cds files as input for resolving the entire CDS model.
    Show/Hide Beta Features