Skip to content

Commit

Permalink
Docu updates for DC formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
martinfrick committed Aug 10, 2023
1 parent 150500e commit 743d360
Show file tree
Hide file tree
Showing 52 changed files with 201 additions and 182 deletions.
3 changes: 3 additions & 0 deletions docu/1-discover/1-discover-tutorial-target/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Discover the Tutorial Target

- **Kyma**
- **Cloud Foundry**

In this tutorial, you will learn how to set up a multitenant Software as a Service (SaaS) application using CAP in your SAP Business Technology Platform (SAP BTP) environment. This use-case can be deployed to the **SAP BTP, Cloud Foundry** and also SAP's managed Kubernetes offering, the **SAP BTP, Kyma Runtime**. You are flexible to choose which runtime suits your needs or skills.

> **Hint** - You will find separate step-by-step tutorials in case the deployment steps differentiate. Ensure to check the chapter introductions, as those will clearly indicate whether a the content targets a specific runtime! Feel free to ignore any content or chapters not related to your chosen runtime!
Expand Down
3 changes: 3 additions & 0 deletions docu/1-discover/2-learn-basics-btp-cf-kyma/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# The Basics of SAP BTP, Cloud Foundry, Kyma and CAP

- **Kyma**
- **Cloud Foundry**

The **SAP Business Technology Platform (SAP BTP)** is an integrated offering comprised of four technology portfolios: database and data management, application development and integration, analytics, and intelligent technologies. The platform offers users the ability to turn data into business value, compose end-to-end business processes, and build and extend SAP applications quickly.

- [The Basics of SAP BTP, Cloud Foundry, Kyma and CAP](#the-basics-of-sap-btp-cloud-foundry-kyma-and-cap)
Expand Down
3 changes: 3 additions & 0 deletions docu/1-discover/3-partners-sap-btp-ecosystem/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Partners in SAP BTP Ecosystem

- **Kyma**
- **Cloud Foundry**

To learn more about how SAP BTP is helping partners and businesses succeed, check out the [Accelerating Innovation and Time to Market with SAP BTP](https://news.sap.com/2022/04/idc-study-on-sap-btp-partners-accelerate-innovation/) article, some [recent partner success stories](https://www.sap.com/products/technology-platform/partners.html) or, if you’re interested in SAP BTP software partnership opportunities with SAP, please visit [SAP PartnerEdge, Build](https://www.sap.com/partners/partner-program/build.html) for more information. Let us also use the chance to provide you with some more input about **SAP Industry Cloud** in this context.


Expand Down
3 changes: 3 additions & 0 deletions docu/1-discover/4-get-idea-saas-applications/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Get the idea of a SaaS application

- **Kyma**
- **Cloud Foundry**

This part of the tutorial is to explain the ideas and advantages of **Software as a Service (SaaS)** applications. You might have heard of SaaS in combination with other abbreviations like **IaaS** (Infrastructure as a Service) and **PaaS** (Platform as a Service). Without the intention to cover all these topics in the greatest detail, let's at least try to cover the basics here. For more information please feel free to consult your favorite search engine provider, which will deliver a ton of results for the search terms above.

SaaS applications are part of our daily life and not just in a B2B world but also in B2C environments. If you think of subscription services like Office365 which is used by a lot of private customers, this is a perfect example of Software as a Service in which Microsoft provides you the well-known Microsoft Office tools as web applications (and as a desktop version if you like). All you need to do is sign up for an account and you're ready to go. No installation, configuration, or updates are required. So let's see how the idea of SaaS evolved throughout the last years.
Expand Down
3 changes: 3 additions & 0 deletions docu/1-discover/5-understand-btp-multitenancy/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Understand SAP BTP Multitenancy

- **Kyma**
- **Cloud Foundry**

In SAP BTP, you can develop and run multitenant applications that can be accessed by multiple consumers (tenants) through a dedicated URL. In this sample scenario, we decided to implement the solution based on a standardized toolset including the SAP Cloud Application Programming (CAP) Model.

## Context
Expand Down
3 changes: 3 additions & 0 deletions docu/1-discover/6-whats-new/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# What's new

- **Kyma**
- **Cloud Foundry**

On this section of the tutorial, you will find a summary of all new features after the initial publication of the tutorial and the GitHub repository.

| Date | Title | Branch | Short description |
Expand Down
4 changes: 2 additions & 2 deletions docu/2-basic/0-introduction-basic-version/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Introduction to the Basic Version

- ### **Kyma**
- ### **Cloud Foundry**
- **Kyma**
- **Cloud Foundry**

The **Basic Version** of the sample application will provide you with the core elements required for a Software as a Service (SaaS) application on SAP Business Technology Platform (SAP BTP).

Expand Down
4 changes: 2 additions & 2 deletions docu/2-basic/1-understand-repo-structure/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Understand the Repository Structure

- ### **Kyma**
- ### **Cloud Foundry**
- **Kyma**
- **Cloud Foundry**

This part of the tutorial will briefly outline the structure of **code** directory, so you're comfortable navigating through the provided GitHub repository. If you are targeting a Cloud Foundry deployment, please ignore the Kubernetes related artifacts like **Dockerfiles**, which are not required for your deployment.

Expand Down
4 changes: 2 additions & 2 deletions docu/2-basic/10-troubleshooting/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Troubleshooting

- ### **Kyma**
- ### **Cloud Foundry**
- **Kyma**
- **Cloud Foundry**

In this section of the **Basic Version** you can find troubleshooting information that might help you in case of errors or issues. The content of this section will be continuously enhanced in the future.

Expand Down
4 changes: 2 additions & 2 deletions docu/2-basic/2-prepare-provider-subaccount/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Prepare the Provider Subaccount

- ### **Kyma**
- ### **Cloud Foundry**
- **Kyma**
- **Cloud Foundry**

In this chapter, you will learn how to prepare your SAP BTP Provider Subaccount for the deployment of the sample SaaS solution by assigning the required entitlements and setting up the foundational components. This includes a SAP HANA Cloud instance which you need to share with your **Cloud Foundry** environment or your **Kyma Cluster** before deployment.

Expand Down
8 changes: 4 additions & 4 deletions docu/2-basic/3-cf-build-deploy-application/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Cloud Foundry - Build and deploy the SaaS application

- ### **Kyma**
- ### **Cloud Foundry**
- **Kyma**
- **Cloud Foundry**


**Important** - This part of the tutorial is required for **Cloud Foundry** deployments only!
Expand Down Expand Up @@ -101,7 +101,7 @@ $ cf deploy mta_archives/susaas_0.0.1.mtar -e ./mtaext/free-tier-private.mtaext
Before you learn how to subscribe new tenants in the next part of the mission, you need to provide two credentials in the Credential Store. These credentials are essential for some parts of the automated subscription process.
2.1. In your provider subaccount, please go to the Instances and Subscriptions menu and click on your **\<SpaceName\>-susaas-credstore** instance or use the **Manage Instance** button.
2.1. In your provider subaccount, please go to the Instances and Subscriptions menu and click on your **\<SpaceName>-susaas-credstore** instance or use the **Manage Instance** button.
[<img src="./images/CS_Service.png" width="400"/>](./images/CS_Service.png?raw=true)
Expand Down Expand Up @@ -133,7 +133,7 @@ Provide the e-mail address (Username) and password (Value) of an SAP BTP user wh
As Value please provide the **Plaintext Password** of your API broker user. This password is required when registering the API broker in any of your consumer subaccounts during automation.
> **Hint** - You created this password in step 1.4 of "[Prepare the SaaS Application for deployment](#1-Prepare-the-SaaS-Application-for-deployment)".
> **Hint** - You created this password in step 1.4 of "[Prepare the SaaS Application for deployment](#1-Prepare-the-SaaS-Application-for-deployment)". <br>
[<img src="./images/SB_PlainText.png" width="500"/>](./images/SB_PlainText.png?raw=true)
As a Username please use the value **broker-user**.
Expand Down
34 changes: 17 additions & 17 deletions docu/2-basic/3-kyma-build-docker-images/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Kyma - Build, Pack and Push your Docker Images

- ### **Kyma**
- ### **Cloud Foundry**
- **Kyma**
- **Cloud Foundry**

**Important** - This part of the tutorial is required for **Kyma** deployments only!

Expand All @@ -25,7 +25,7 @@ Let us have a brief look at the tool prerequisites, which are essential to build

If you are facing any issues during the following steps of our tutorial, please feel free to consult the excellent **Developer Tutorial** on **Deploy Your CAP Application on SAP BTP Kyma Runtime**. It describes similar steps and will get you covered in great detail, in case you get stuck in our sample scenario.

https://developers.sap.com/mission.btp-deploy-cap-kyma.html
[https://developers.sap.com/mission.btp-deploy-cap-kyma.html](https://developers.sap.com/mission.btp-deploy-cap-kyma.html)

## 1. Prerequisites

Expand Down Expand Up @@ -138,7 +138,7 @@ These components will be containerized in Docker Images in the following steps.
3.1. Run the following npm script (from within your *deploy/kyma* directory), which will *build* all Docker Images using **SAP Standard Docker Images** and **Cloud Native Buildpacks**.

> **Hint** - If you use e.g. DockerHub as a Container Registry, please put in your **username** (e.g., johndoe) as Container Image Prefix placeholder. If you use the GitHub Container Registry, the prefix will look similar to **ghcr.io/\<namespace\>** (e.g. ghcr.io/johndoe). All generated Docker Images will be automatically prefixed with this label!
> **Hint** - If you use e.g. DockerHub as a Container Registry, please put in your **username** (e.g., johndoe) as Container Image Prefix placeholder. If you use the GitHub Container Registry, the prefix will look similar to **ghcr.io/\<namespace>** (e.g. ghcr.io/johndoe). All generated Docker Images will be automatically prefixed with this label!
> **Hint** - Using devices with ARM chips (e.g., Apple M1) the build process involving Cloud Native Buildpacks might take several minutes. Please do not immediately cancel the build if things appear to be stuck, but wait some time for the process to continue (especially while the SBOM is being generated)!
Expand Down Expand Up @@ -171,7 +171,7 @@ Building **Dockerfiles** for Kubernetes workloads is not always easy. Especially

Once again, I highly suggest to have a quick break and scroll through the excellent blog post of Maximilian Streifeneder, who gets you covered on the topic of Paketo as well as some nice little tricks how to further analyze generated Docker Images!

https://blogs.sap.com/2023/03/07/surviving-and-thriving-with-the-sap-cloud-application-programming-model-deployment-to-sap-btp-kyma-runtime/
[https://blogs.sap.com/2023/03/07/surviving-and-thriving-with-the-sap-cloud-application-programming-model-deployment-to-sap-btp-kyma-runtime/](https://blogs.sap.com/2023/03/07/surviving-and-thriving-with-the-sap-cloud-application-programming-model-deployment-to-sap-btp-kyma-runtime/)

Docker Images created using Paketo and Cloud Native Buildpacks are secure, efficient, production-ready and come with a lot of features, which are hard to provided using Dockerfiles and would require much more manual effort. To get an idea of the features provided by Cloud Native Buildpacks, check out the official documentation ([click here](https://buildpacks.io/features/)). To learn about the general concepts behind Cloud Native Buildpacks (turning your source-code into a read-to-use Docker Image), check out the respective documentation ([click here](https://buildpacks.io/docs/concepts/)).

Expand All @@ -186,7 +186,7 @@ As the API Service is based on CAP and Node.js, for the initial build or any cha

This simplifies the containerization process and allows you to build a Docker Image without the necessity of maintaining a separate Dockerfile for Node.js workloads. During the build process, Paketo will take the content of the *gen/api* directory and put it into the working directory of a Node.js Docker Image. This image is based on the latest and stable Cloud Native Buildpacks.

**Npm script to build the Docker Image using Paketo** ([/deploy/kyma/package.json](../../../deploy/kyma/package.json))
**Npm script to build the Docker Image using Paketo** ([*/deploy/kyma/package.json*](../../../deploy/kyma/package.json))

```json
"build:api": "pack build sap-demo/susaas-api --path ../../code/gen/api --builder paketobuildpacks/builder:base --buildpack gcr.io/paketo-buildpacks/nodejs -e BP_LAUNCHPOINT=./node_modules/@sap/cds/bin/cds-serve.js"
Expand All @@ -203,7 +203,7 @@ As the central Backend Service is also based on CAP, for the initial build or an

Doing so (as for the API Service), a Docker Image can be build without having to maintain a separate Dockerfile. During the build process, Paketo will take the content of the *gen/srv* directory, and place it into the working directory a Node.js Docker Image. Again, this image is based on the latest and stable Cloud Native Buildpacks.

**Npm script to build the Docker Image using Paketo** ([/deploy/kyma/package.json](../../../deploy/kyma/package.json))
**Npm script to build the Docker Image using Paketo** ([*/deploy/kyma/package.json*](../../../deploy/kyma/package.json))

```json
"build:srv": "pack build sap-demo/susaas-srv --path ../../code/gen/srv --builder paketobuildpacks/builder:base --buildpack gcr.io/paketo-buildpacks/nodejs -e BP_LAUNCHPOINT=./node_modules/@sap/cds/bin/cds-serve.js"
Expand All @@ -220,7 +220,7 @@ Therefore, we created a tiny Dockerfile which is using the official SAP Docker I

> **Hint** - The package.json file is part of the directory for local testing purposes only. As the SAP-managed Docker Image *sapse/approuter* already contains a package.json file, we will reuse the start script of this SAP-provided package.json scripts.
**Dockerfile based on sapse/approuter Docker Image** ([/code/router/Dockerfile](../../../code/router/Dockerfile))
**Dockerfile based on sapse/approuter Docker Image** ([*/code/router/Dockerfile*](../../../code/router/Dockerfile))

```Dockerfile
# Image based on SAP provided sapse/approuter image
Expand All @@ -242,7 +242,7 @@ COPY . .
CMD [ "npm", "start" ]
```

**Build Docker Image based on Dockerfile above** ([/deploy/kyma/package.json](../../../deploy/kyma/package.json))
**Build Docker Image based on Dockerfile above** ([*/deploy/kyma/package.json*](../../../deploy/kyma/package.json))

> **Hint** - This following npm script will build a Docker Image based on the Dockerfile located in the */code/router* directory and will tag it with *sap-demo/susaas-router*. "sap-demo" has to be replaced by the prefix also used in step 3.1, if you want to run this command standalone.
Expand All @@ -259,7 +259,7 @@ For the API Service Broker (which is actually just a generic Node.js workload ba

This way (as for the API and SaaS Backend Service), a Docker Image can be build without maintaining a separate Dockerfile. During the build process, Paketo will take the content of the *broker* directory, and place it into the working directory of a Node.js Docker Image. This Docker Image is again based on the latest Cloud Native Buildpacks.

**Npm script to build the Docker Image using Paketo** ([/deploy/kyma/package.json](../../../deploy/kyma/package.json))
**Npm script to build the Docker Image using Paketo** ([*/deploy/kyma/package.json*](../../../deploy/kyma/package.json))

```json
"build:broker": "pack build sap-demo/susaas-broker --path ../../code/broker --builder paketobuildpacks/builder:base --buildpack gcr.io/paketo-buildpacks/nodejs -e BP_LAUNCHPOINT=./start.js"
Expand All @@ -276,27 +276,27 @@ As this Docker Image is maintained by SAP, there is no need to make use of Cloud

The *resources* folder (within the *code/app/html5-deployer* directory) contains the zipped UI5 modules (which you need to build upfront using the *npm run ui:apps* script - [see here](#2-build-your-components)). If you followed all previous tutorial steps, the respective zip files should already exist, as the respective command will automatically run the *build* scripts in the *package.json* files of our UI5 modules.

**Npm script to trigger the build of a single UI module** ([/deploy/kyma/package.json](../../../deploy/kyma/package.json))
**Npm script to trigger the build of a single UI module** ([*/deploy/kyma/package.json*](../../../deploy/kyma/package.json))

```json
"ui:admin-projects": "npm run build:copy --prefix ../../code/app/ui-admin-projects/"
```

**Npm scripts to build a UI module and copy zip to html5 app deployer** ([/code/app/ui-admin-projects/package.json](../../../code/app/ui-admin-projects/package.json))
**Npm scripts to build a UI module and copy zip to html5 app deployer** ([*/code/app/ui-admin-projects/package.json*](../../../code/app/ui-admin-projects/package.json))

```json
"scripts": {
"build:copy": "npm run build && npm run copy",
"build": "ui5 build preload --clean-dest --config ui5-deploy.yaml --include-task=generateCachebusterInfo",
"copy": "shx mkdir -p ../html5-deployer/resources/ && shx cp -rf ./dist/*.zip ../html5-deployer/resources/"
},
}
```

Similar to the Application Router, the Dockerfile residing in the *code/app/html5-deployer* folder, copies the *html5-deployer* directory content into the working directory of the resulting Docker Image, which is based on the SAP-managed *sapse/html5-app-deployer* image.

> **Hint** - The package.json file is part of the *code/app/html5-deployer* directory for local testing purposes only. As the Docker Base Image *sapse/html5-app-deployer* already contains a corresponding package.json file, we will reuse the start script of this SAP-provided package.json.
**Dockerfile based on sapse/html5-app-deployer Docker Image** ([/code/app/html5-deployer/Dockerfile](../../../code/app/html5-deployer/Dockerfile))
**Dockerfile based on sapse/html5-app-deployer Docker Image** ([*/code/app/html5-deployer/Dockerfile*](../../../code/app/html5-deployer/Dockerfile))

```Dockerfile
# Image based on SAP provided sapse/html5-app-deployer image
Expand All @@ -318,7 +318,7 @@ COPY . .
CMD [ "npm", "start" ]
```

**Build Docker Image based on Dockerfile above** ([/deploy/kyma/package.json](../../../deploy/kyma/package.json))
**Build Docker Image based on Dockerfile above** ([*/deploy/kyma/package.json*](../../../deploy/kyma/package.json))

```json
"build:html5-deployer": "docker build -t sap-demo/susaas-html5-deployer ../../code/app/html5-deployer"
Expand All @@ -332,7 +332,7 @@ As the data model of the shared database container is also based on CAP, for the

After running the CDS build (compiling the CDS files of our CAP Backend, CAP API, Tenant and shared data model), the required Docker Image (containing an HDI deployer for the shared data model) is build using Paketo and Cloud Native Buildpacks. This simplifies the build process and allows us to build a Docker Image without the necessity of maintaining a separate Dockerfile. During the build process, Paketo will take the content of the *gen/db-com* directory and place it into the working directory of a Node.js Docker Image. This image is based on the latest Cloud Native Buildpacks.

**Npm script to build the Docker Image using Paketo** ([/deploy/kyma/package.json](../../../deploy/kyma/package.json))
**Npm script to build the Docker Image using Paketo** ([*/deploy/kyma/package.json*](../../../deploy/kyma/package.json))

```json
"build:db-com": "pack build sap-demo/susaas-db-com --path ../../code/gen/db-com --builder paketobuildpacks/builder:base --buildpack gcr.io/paketo-buildpacks/nodejs -e BP_LAUNCHPOINT=./node_modules/@sap/hdi-deploy/deploy.js"
Expand All @@ -349,7 +349,7 @@ To allow Helm to pull your Docker Images during the deployment process, you need
After all your Docker Images are build using **Cloud Native Buildpacks** or **SAP Standard Images**, you can push them to your Container Registry. To do so, please ensure you successfully logged in to your registry of choice (*docker login*) before running the following npm script.

> **Hint** - If you use e.g. DockerHub as a Container Registry, please put in your **username** (e.g., johndoe) as Container Image Prefix placeholder. If you use the GitHub Container Registry, the prefix will look similar to **ghcr.io/\<namespace\>** (e.g. ghcr.io/johndoe). All generated Docker Images will be automatically prefixed with this label!
> **Hint** - If you use e.g. DockerHub as a Container Registry, please put in your **username** (e.g., johndoe) as Container Image Prefix placeholder. If you use the GitHub Container Registry, the prefix will look similar to **ghcr.io/\<namespace>** (e.g. ghcr.io/johndoe). All generated Docker Images will be automatically prefixed with this label!
```sh
# Run in ./deploy/kyma #
Expand Down
Loading

0 comments on commit 743d360

Please sign in to comment.