Skip to content
Search

    Deploy to Cloud Foundry

    Learn here about the essential steps to deploy a CAP application to SAP BTP Cloud Foundry environment.

    This guide is also available as CAP Notebook.

    Intro & Overview

    After completing the functional implementation of your CAP application by following the Getting Started or Cookbook guides, you would finally deploy it to the cloud for production. The essential steps are illustrated in the following graphic:

    deploy-setps.drawio

    First, you apply these steps manually in an ad-hoc deployment, as described in this guide. Then, after successful deployment, you automate them using CI/CD pipelines.


    This guide is available for Node.js and Java. Press v to switch, or use the toggle.


    Prerequisites

    The following sections are based on our cap/samples/bookshop project. Download or clone the repository, and exercise the following steps in the bookshop subfolder:

    git clone https://github.com/sap-samples/cloud-cap-samples samples
    cd samples/bookshop
    

    The following sections are based on a new Java project that you can create like this:

    cds init bookshop --add java,samples
    cd bookshop
    

    If you want to use a ready-to-be-deployed sample, see our java/samples.


    In addition, you need to prepare the following:

    1. SAP BTP with SAP HANA Cloud Database up and Running

    As starting the SAP HANA database takes several minutes, we recommend doing these steps early on. In trial accounts, you need to start the database every day.

    2. Latest Versions of @sap/cds-dk

    Ensure you have the latest version of @sap/cds-dk installed globally:

    npm -g outdated        #> check whether @sap/cds-dk is listed
    npm i -g @sap/cds-dk   #> if necessary
    

    Likewise, ensure the latest version of @sap/cds is installed in your project:

    npm outdated           #> check whether @sap/cds is listed
    npm i @sap/cds         #> if necessary
    

    3. Cloud MTA Build Tool

    • Run mbt in a terminal to check whether you’ve installed it.
    • If not, install it following the instructions in the MTA Build Tool’s documentation.
    • For macOS/Linux machines best is to install using npm:
      npm i -g mbt
      

    4. Cloud Foundry CLI w/ MTA Plugins

    Prepare for Production

    If you followed CAP’s grow-as-you-go approach so far, you’ve developed your application with an in-memory database and basic/mock authentication. To prepare for production you need to ensure respective production-grade choices are configured, as illustrated in the following graphic.

    deploy-overview.drawio

    We’ll use the cds add <facets> CLI command for that, which ensures the required services are configured correctly and corresponding package dependencies are added to your package.json.

    1. Using SAP HANA Database

    While we used SQLite as a low-cost stand-in during development, we’re going to use a managed SAP HANA database for production:

    cds add hana --for production
    

    Learn more about using SAP HANA for production.

    2. Using XSUAA-Based Authentication

    Configure your app for XSUAA-based authentication:

    cds add xsuaa --for production
    

    Learn more about SAP Authorization and Trust Management/XSUAA.

    This will also generate an xs-security.json file, with roles/scopes derived from authorization-related annotations in your CDS models. Ensure to rerun cds compile --to xsuaa, as documented in the Authorization guide whenever there are changes to these annotations.

    3. Using App Router as Gateway

    Configure your app to use App Router as gateway:

    cds add approuter --for production
    

    The App Router acts as a single point-of-entry gateway to route requests to. In particular, it ensures user login and authentication in combination with XSUAA.

    Learn more about the SAP BTP Application Router.

    If you want to use the SAP Launchpad service instead of the standalone App Router, learn about adding the SAP Launchpad service in the End-to-End tutorial.

    4. Using MTA-Based Deployment

    We’ll be using the so-called Cloud MTA Build Tool to execute the deployment. The modules and services are configured in an mta.yaml deployment descriptor file, which we generate with:

    cds add mta
    

    Learn more about MTA-based deployment


    The previous steps are required only once in a project’s lifetime. With that done, we can repeatedly deploy the application.


    Deploy as Saas
    If you want to deploy the app as a multitenant SaaS solution, you can now fast-forward to the SaaS guide. Otherwise follow this guide and decider later to switch to SaaS.

    5. Freeze Dependencies

    Deployed applications should freeze all their dependencies, including transient ones. Create a package-lock.json file for that:

    npm update --package-lock-only
    

    Learn more about dependency management for Node.js

    Note: You should regularly update your package-lock.json to consume latest versions and bug fixes. Do so by running this command again, for example each time you deploy a new version of your application.

    Build & Assemble

    Build deployables with cds build

    Run cds build to generate additional deployment artifacts and prepare everything for production in a local ./gen folder as a staging area. While cds build is included in the next step mbt build, you can also run it selectively as a test, and to inspect what is generated:

    cds build --production
    
    mvn clean install
    

    Learn more about running and customizing cds build.

    Assemble with mbt build

    Now, we use the mbt build tool to assemble everything into a single mta.tar archive.

    mbt build -t gen --mtar mta.tar
    

    Got errors? See the troubleshooting guide.

    Learn how to reduce the MTA archive size during development.

    Deploy to Cloud

    Finally, we can deploy the generated archive to Cloud Foundry:

    cf deploy gen/mta.tar
    

    You need to be logged in to Cloud Foundry.

    This process can take some minutes and finally creates a log output like this:

    [...]
    Application "bookshop" started and available at
    "[org]-[space]-bookshop.landscape-domain.com"
    [...]
    

    Copy and open this URL in your web browser. It’s the URL of approuter application.

    Inspect Deployed Apps in BTP Cockpit

    Visit the “Applications” section in your SAP BTP cockpit to see the deployed apps:

    The screenshot shows the SAP BTP cockpit, when a user navigates to his dev space in the trial account and looks at all deployed applications.

    We didn’t do the admin role assignment for the admin service. You need to create a role collection and assign the role and your user to get access.

    Got errors? See the troubleshooting guide.


    Appendices

    Deploy using cf push

    As an alternative to MTA-based deployment, you can choose Cloud Foundry-native deployment using cf push, or cf create-service-push respectively.

    Prerequisites

    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.

    Add a manifest.yml

    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

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

    cds build --production
    

    Learn how cds build can be configured.

    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 binds 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
    routes:            bookshop-srv-....cfapps.sap.hana.ondemand.com
    

    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.