Deploy to Cloud Foundry
Learn here about the essential steps to deploy a CAP application 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
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
- 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
- A Cloud Foundry quota plan assigned to your space
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
- Run
cf
in a terminal to check whether you’ve installed it. - If not, install it following the instructions in the Cloud Foundry CLI documentation.
- In addition, ensure to have the MTA plugin for the Cloud Foundry CLI installed.
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 yourpackage.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
Now, we use the mbt
build tool to build and assemble everything into a single mta.tar
archive, in a local ./gen
folder as a staging area.
mbt build -t gen --mtar mta.tar
Got errors? See the troubleshooting guide.
Learn how to reduce the MTA archive size during development.
Optional — Running cds build
Manually
The mbt build
command runs cds build
to generate additional deployment artifacts and prepare everything in a ./gen
folder. You can also run a build selectively as a test, and to inspect what is generated:
cds build --production
mvn clean install
Learn more about running and customizing cds build
.
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.
You can also visit the “Applications” section in your SAP BTP cockpit to see the deployed apps:
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.
Next Steps
Turn the app into a multitenant SaaS solution. See the SaaS guide for more.
Learn about how to automate deployments using CI/CD pipelines.