Team onboarding guide

guides/deploy/_menu.md

@@ -1,4 +1,5 @@
 
+# [Team Onboarding](team-onboarding)
 # [Deploy to Cloud Foundry](to-cf)
 # [Deploy to Kyma/K8s](to-kyma)
 # [Deploy with CI/CD](cicd)

guides/deploy/cicd.md

@@ -22,6 +22,10 @@ cds add github-actions
 ```
 > You can also use `cds add gha` as a shortcut.
 
+<span id="github-actions-internal" />
+
+> If your Node.js project has no tests yet, run `cds add test` to generate service tests.
+
 ### Deploy to Staging
 
 The created workflows do a _Staging_ deployment for pushes on the `main` branch, usually after merging pull requests.

guides/deploy/team-onboarding.md

@@ -0,0 +1,215 @@
+---
+description: >
+  Prepare a team landscape on SAP BTP for app deployment and CI/CD.
+status: released
+---
+
+# Team Onboarding
+
+{{ $frontmatter.description }}
+
+[[toc]]
+
+## Overview
+
+Assume your team is developing a complex CRM solution with multiple apps and services.
+The team needs a shared landscape that keeps development separate from releases.
+
+::: info A subaccount for each stage
+
+- **Sandbox** for development and experiments.
+- **Staging** for integration checks.
+- **Production** for releases to users.
+:::
+
+Each app has its own repository and release pipeline.
+
+::: tip Shared Setup
+
+Typically, one operator sets up the shared landscape so the whole team can deploy apps with `cds up` without repeating the setup.
+:::
+
+## 1. Choose a Runtime
+
+Choose the runtime that fits your team before provisioning the landscape:
+
+### Cloud Foundry
+
+Cloud Foundry is an opinionated runtime where the platform manages buildpacks, routing, and bound services. It fits teams that want to focus on application code.
+
+### Kyma
+
+Kyma is a managed Kubernetes runtime where you own the container images, manifests, and networking. Choose it when you need more control or already work with Kubernetes.
+
+## 2. Install the Tools
+
+We assume you've installed the basic tooling from [Getting Started](../../get-started/#initial-setup). Install Terraform and the BTP CLI, then the tools for your chosen runtime:
+
+::: code-group
+~~~sh [macOS]
+brew tap hashicorp/tap
+brew install hashicorp/tap/terraform
+brew install --cask btp
+~~~
+~~~sh [Linux]
+brew tap hashicorp/tap
+brew install hashicorp/tap/terraform
+btp_arch=$(uname -m)
+btp_arch=${btp_arch/x86_64/amd64}
+btp_arch=${btp_arch/aarch64/arm64}
+curl -L "https://tools.hana.ondemand.com/additional/btp-cli-linux-$btp_arch-2.116.3.tar.gz" -o btp.tar.gz
+tar -xzf btp.tar.gz
+sudo install -m 755 "linux-$btp_arch/btp" /usr/local/bin/btp
+~~~
+~~~powershell [Windows]
+winget install --silent Hashicorp.Terraform
+winget install --silent SAP.btp
+
+# Open a new terminal after installation.
+# For WSL, follow the Linux steps.
+~~~
+:::
+
+### Cloud Foundry Tools
+
+::: code-group
+~~~sh [macOS/Linux]
+brew install cloudfoundry/tap/cf-cli@8
+~~~
+~~~powershell [Windows]
+winget install --silent CloudFoundry.CLI.v8
+winget install --silent ezwinports.make
+~~~
+:::
+
+In your terminal:
+
+~~~sh
+npm install -g mbt
+cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org
+cf install-plugin -f multiapps
+cf install-plugin -f html5-plugin
+~~~
+
+### Kyma Tools
+
+::: code-group
+~~~sh [macOS/Linux]
+brew install kubernetes-cli helm buildpacks/tap/pack
+brew install int128/kubelogin/kubelogin
+~~~
+~~~powershell [Windows]
+winget install --silent Kubernetes.kubectl
+winget install --silent Helm.Helm
+winget install --silent int128.kubelogin
+Invoke-WebRequest https://github.com/buildpacks/pack/releases/download/v0.40.10/pack-v0.40.10-windows.zip -OutFile pack.zip
+Expand-Archive pack.zip -DestinationPath "$env:LOCALAPPDATA\Microsoft\WinGet\Links" -Force
+~~~
+:::
+
+For app deployment, you also need [Docker](https://docs.docker.com/get-docker/) and a [container registry](to-kyma#get-access-to-a-container-registry).
+
+## 3. Get a Global Account
+
+[Request a global account](https://help.sap.com/docs/btp/sap-business-technology-platform/getting-global-account) and [an IAS tenant](https://help.sap.com/docs/cloud-identity-services/cloud-identity-services/get-your-tenant) from your BTP admin. You need **Global Account Administrator** access and permission to assign IAS authorization policies.
+
+<span id="team-account-requests" />
+
+Note your global account subdomain and IAS hostname.
+
+## 4. Provision the Landscape
+
+Log in to BTP and create a directory for your team:
+
+~~~sh
+btp login --sso
+mkdir CRM
+cd CRM
+~~~
+
+Choose the matching variant:
+
+::: code-group
+~~~sh [Cloud Foundry]
+cf login --sso -a https://api.cf.eu10.hana.ondemand.com
+cds add terraform --cf
+~~~
+~~~sh [Kyma]
+cds add terraform --k8s
+~~~
+:::
+
+You will be prompted for some inputs:
+
+| Prompt | Enter |
+| --- | --- |
+| Global account subdomain | Your global account subdomain |
+| Region | Your region, for example `eu10`. [Learn more about regions in BTP.](https://help.sap.com/docs/btp/sap-business-technology-platform/regions){.learn-more style="margin-top:5px"} |
+| `idp_origin_key` | Leave empty for SAP's default identity provider; otherwise use your administrative identity provider's origin key |
+| Email(s) | One or more team admin emails separated by commas, with your login email first |
+| IAS tenant hostname | Your team's IAS hostname for application trust, without `https://` |
+
+<br>
+
+The command creates the Terraform configuration in `CRM/` for these stages:
+
+| Subaccount | CF org / Kyma cluster | Space / Namespace |
+| --- | --- | --- |
+| CRM Sandbox | `crm-sandbox` | `team` |
+| CRM Staging | `crm-staging` | `ci` |
+| CRM Production | `crm-production` | `ci` |
+
+### Apply
+
+Use your BTP CLI login:
+
+::: code-group
+~~~sh [macOS/Linux]
+export USE_BTPCLI_SESSION=true
+~~~
+~~~powershell [Windows]
+$env:USE_BTPCLI_SESSION = 'true'
+~~~
+:::
+
+Initialize the configuration, review the plan, then apply it:
+
+~~~sh
+terraform init
+terraform plan
+terraform apply
+~~~
+
+> You'll be prompted for the HANA SYSTEM password.
+
+Applying the configuration creates the subaccounts, runtime, admin access, IAS trust, and a HANA database per stage. For Kyma, it also prepares the namespaces, service operator, and HANA mappings.
+
+::: tip Allow time for provisioning
+Provisioning HANA usually takes around 20–30 minutes. When setting up Kyma, you may be asked to sign in through your browser for cluster access.
+:::
+
+## 5. Deploy to Sandbox
+
+Deploy your first app to *Sandbox* using the guide for your runtime:
+
+### Cloud Foundry
+
+Prepare and deploy your app with `cds up --to cf`.
+
+[Learn more in Deploy to Cloud Foundry.](to-cf){.learn-more}
+
+### Kyma
+
+Prepare and deploy your app with `cds up --to k8s`.
+
+[Learn more in Deploy to Kyma.](to-kyma){.learn-more}
+
+## 6. Set Up CI/CD
+
+Once your app runs in *Sandbox*, set up CI/CD to roll out changes to *Staging* and *Production*.
+
+::: tip Release flow
+Pushes to `main` deploy to *Staging*. Published GitHub releases deploy to *Production*.
+:::
+
+[Learn more in Deploy with CI/CD.](cicd){.learn-more}

guides/deploy/to-cf.md

@@ -117,16 +117,24 @@ cds add hana
 
 ### 2. Authorization/Authentication
 
-Configure your app for XSUAA-based authentication:
+Choose IAS with AMS authorization, or XSUAA:
 
-```sh
+::: code-group
+```sh [IAS]
+cds add ias
+cds add ams
+```
+```sh [XSUAA]
 cds add xsuaa
 ```
+:::
 
-::: tip This will also generate an `xs-security.json` file
-The roles/scopes are derived from authorization-related annotations in your CDS models. Ensure to rerun `cds compile --to xsuaa`, as documented in the [_Security_ guide](../security/cap-users#xsuaa-roles) whenever there are changes to these annotations.
+::: tip XSUAA roles
+`cds add xsuaa` generates an `xs-security.json` file from authorization annotations in your CDS models. Rerun `cds compile --to xsuaa` when these annotations change.
 :::
 
+[Learn more about IAS authentication.](../security/authentication#ias-auth){.learn-more}
+[Learn more about AMS authorization.](../security/cap-users#roles-assignment-ams){.learn-more}
 [Learn more about SAP Authorization and Trust Management/XSUAA.](https://discovery-center.cloud.sap/serviceCatalog/authorization-and-trust-management-service?region=all){.learn-more}
 
 ### 3. Remote Service Consumption {#remote-services}
@@ -160,19 +168,23 @@ cds add mta
 
 ### 5. User Interfaces {#add-ui}
 
-#### Option A: SAP Cloud Portal
+#### Option A: App Router
 
-If you intend to deploy **multitenant** applications with a UI, set up the [HTML5 Application Repository](https://discovery-center.cloud.sap/serviceCatalog/html5-application-repository-service) in combination with the [SAP Cloud Portal service](https://discovery-center.cloud.sap/serviceCatalog/cloud-portal-service):
+Add an App Router to your project:
 
 ```sh
-cds add portal
+cds add approuter
 ```
 
-::: tip `cds add portal` adds an _App Router_ configuration to your project
+::: tip `cds add approuter` adds an _App Router_ configuration to your project
 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 or IAS.
 :::
 
+For the UI from `cds add sample`, the build includes its static files and uses `/fiori-apps.html` as the welcome page.
+
+[Learn more about the SAP BTP Application Router.](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/01c5f9ba7d6847aaaf069d153b981b51.html?locale=en-US){.learn-more}
+
 #### Option B: SAP BTP Application Frontend <Beta />
 
 For **single-tenant** applications, you can use the new [SAP BTP Application Frontend](https://help.sap.com/docs/application-frontend-service) service:
@@ -192,19 +204,6 @@ cds add workzone
 
 This approach uses the **managed App Router** provided by SAP Fiori Launchpad — you don't need to deploy your own. Instead, destinations are configured.
 
-<br>
-
-You might also use a custom App Router setup without SAP BTP Cloud Portal service:
-
-```sh
-cds add approuter
-```
-[Learn more about the SAP BTP Application Router.](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/01c5f9ba7d6847aaaf069d153b981b51.html?locale=en-US){.learn-more}
-<br>
-However, in this case, you need to create symlinks from your _app_ folders to make them visible to the deployed App Router.
-The [samples _modulith_](https://github.com/capire/samples) project uses this setup for serving a static _index.html_ consuming Vue.js via CDN.
-
-[Find the symlink directory in the App Router's _resources_ folder](https://github.com/capire/samples/tree/main/.deploy/app-router/resources){.learn-more}
 :::
 
 ### 6. Optional: Multitenancy { #add-multitenancy }
@@ -229,7 +228,7 @@ The previous steps are required _only once_ in a project's lifetime. With that d
 Make sure you are logged in to Cloud Foundry and target the space you want to deploy to:
 ```sh
 cf login --sso  # to log on with SAP Universal ID
-cf target
+cf target -o <org> -s <space>
 ```
 [Learn more about `cf login`](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/7a37d66c2e7d401db4980db0cd74aa6b.html){.learn-more}
 
@@ -311,7 +310,9 @@ Visit the "Applications" section in your [SAP BTP cockpit](https://help.sap.com/
 ![The screenshot shows the SAP BTP cockpit, when a user navigates to their dev space in the trial account and views all deployed applications.](./assets/apps-cockpit.png)
 
 ::: tip Next up: Assign the _admin_ role
-To access the admin APIs, assign the _admin_ role required by the `AdminService`. By default, CAP creates a **role collection** named _admin‑\<org\>‑\<space\>_. [Assign it to your user](https://help.sap.com/docs/btp/sap-business-technology-platform/assign-user-groups-to-role-collections) to get access.
+With IAS and AMS, assign the `cap.admin` policy to your user in the [IAS Administration Console](../security/cap-users#ams-deployment).
+
+With XSUAA, CAP creates a **role collection** named _admin (\<app\> \<org\>-\<space\>)_. [Assign it to your user](https://help.sap.com/docs/btp/sap-business-technology-platform/assign-user-groups-to-role-collections) to access the admin APIs.
 :::
 
 ### Use MTA Extensions with `cds up`