Deploy to Cloud Foundry ​

A comprehensive guide on deploying applications built with SAP Cloud Application Programming Model (CAP) to SAP BTP Cloud Foundry environment.

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:

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 ​

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

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

cds init bookshop --add java,samples
cd bookshop

cds init bookshop --add java,samples
cd bookshop

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

• Access to SAP BTP, for example a trial
• An SAP HANA Cloud database running in your subaccount
• Entitlement for hdi-shared service plan for your subaccount
• A Cloud Foundry space

2. Latest Versions of @sap/cds-dk ​

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

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

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

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 according to the MTA Build Tool's documentation.
• For macOS/Linux machines best is to install using npm:
  sh

  npm i -g mbt

  npm i -g mbt

4. Cloud Foundry CLI w/ MTA Plugins ​

• Run cf -v in a terminal to check whether you've installed version 8 or higher.
• If not, install or update it according to the Cloud Foundry CLI documentation.
• In addition, ensure to have the MTA plugin for the Cloud Foundry CLI installed.
  sh

  cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org
  cf install-plugin multiapps

  cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org
  cf install-plugin multiapps

① 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:

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 ​

cds add hana --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

cds add xsuaa --for production

Learn more about SAP Authorization and Trust Management/XSUAA.

3. Using MTA-Based Deployment ​

We'll be using the 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

cds add mta

Learn more about MTA-based deployment.

4. Using App Router as Gateway ​

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.

Two deployment options are available:

• Managed App Router: for scenarios where SAP Fiori Launchpad (FLP) is the entry point to access your applications, the Managed App Router provided by SAP Fiori Launchpad is available. See the end-to-end tutorial for the necessary configuration in mta.yaml and on each SAP Fiori application.

• Custom App Router: for scenarios without SAP Fiori Launchpad, the app router needs to be deployed along with your application. Use the following command to enhance the application configuration:

  sh

  cds add approuter --for production

  cds add approuter --for production

Learn more about the SAP BTP Application Router.

5. Optional: Deploy as SaaS ​

If you want to deploy the app as a multitenant SaaS solution, you can now fast-forward to the SaaS guide. You can also continue with this guide and make your choice to switch to SaaS later.

6. Freeze Dependencies ​

npm update --package-lock-only

npm update --package-lock-only

② 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

cds build --production

Learn more about running and customizing cds build.

Assemble with mbt build ​

ln -sf ../package-lock.json

ln -sf ../package-lock.json

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

mbt build -t gen --mtar mta.tar

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

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"
[…]

[…]
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 your approuter application.

Inspect Deployed Apps in BTP Cockpit ​

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

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

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

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 Cloud Foundry services shall be created. The services are derived from the service bindings in package.json using the cds.requires configuration.

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

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.

Push the Application ​

This command creates service instances, pushes the applications and binds the services to the application with a single call:

cf create-service-push

cf create-service-push

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 deployment 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

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.

cf logs <app-name>-db-deployer --recent

cf logs <app-name>-db-deployer --recent

Got errors? See the troubleshooting guide.