Setup Automator for SAP Business Technology Platform

Description

This repository provides the user with a script to automate the setup of an SAP Business Technology Platform (SAP BTP) account and to learn how this is done with the various command line interfaces and tools that to run inside a Docker container.

This includes:

Setup of your SAP BTP account
Entitlement of services
Subscriptions to applications and creation of service instances with service keys
Addition of administrator users to global account and subaccounts
Setup of roles and role collections, assignment of roles collections to users
Deployment of complete applications
Unrolling created setup

Get a quick overview & demo of the btp-setup-automator through this video:

Configuration

As a developer you configure your use case inside a usecase.json file with all services and subscriptions that you need (find some sample use cases here including their detailed descriptions). The JSON schema btpsa-usecase.json makes it fairly simple to create your own use case file as you can see in this video:

You find more information on the sample use cases in the use cases document.

Pre-requisites

To use the scripts, this is what you need to do first:

Get an SAP BTP trial account, or a productive SAP BTP account (recommended) where you can make use of the free tier service plans
Install a Docker engine

⚠ NOTE: Be aware of the terms of Docker for usage in enterprises. For details read Docker is Updating and Extending Our Product Descriptions.

In case you are new to the containers topic, we strongly recommended that you install and setup MS Visual Studio Code (VS Code), too:

Install VS Code - this will be your development environment.
Install the VS Code Dev Containers extension for connecting to and using Docker containers.

Download and Run

Once the pre-requisites above are all met, you can either use one of the pre-built Docker images for the btp-setup-automator, or build it yourself.

Option 1: Start Docker Container via Pre-Built Image (recommended)

This is the fastest way to use the btp-setup-automator. We offer two images for the btp-setup-automator:

The release image: This is a stable version of the btp-setup-automator and corresponds to the latest release visible on the release section of the repository. The corresponding code is taken from the main branch of the repository.
The dev image: This is an up-to-date version of the btp-setup-automator. It usually contains newer features and fixes but was not yet officially released. The corresponding code is taken from the dev branch of the repository.

Open a terminal window on your machine and run the following command to pull the Docker image from the GitHub repository and start a container based upon it.

For the release image:

docker container run --rm -it --name "btp-setup-automator" "ghcr.io/sap-samples/btp-setup-automator:latest"

For the dev image:

docker container run --rm -it --name "btp-setup-automator" "ghcr.io/sap-samples/btp-setup-automator-dev:dev"

Here's a brief explanation of the options used:

--rm causes the container to be automatically cleaned up (removed) when you're done with it (when it stops)
-it is short for -i -t and together make the container accessible and interactive (for you to work within)
--name specifies a name for the container (rather than have Docker generate a random one)

You may need to authenticate with GitHub's container registry at ghcr.io (you'll know you need to do this if you get a "denied" error when you run the above command). If this is the case, you'll need to create a Personal Access Token (PAT) with the read:packages scope, and then run this command to log in, using the PAT as the password, when prompted:
docker login ghcr.io --username <your GitHub username>

You'll notice that the prompt in your terminal has changed, because you are now working inside the Docker container that you just started.

You can now run the main script btpsa with the following command and you'll be deploying a CAP application on your SAP BTP Trial account (the default use case).

./btpsa

The tool starts to execute and the only thing you need to type in is your password for your SAP BTP account.

📝 Tip - If you are already using VS Code, you should execute this command instead, so that the container runs "detached" (-d) from your command line session. Here teh command when using the release image
docker container run --rm -it -d --name "btp-setup-automator" "ghcr.io/sap-samples/btp-setup-automator:latest"

You can also use the provided run files to pull the image from the registry and start the container via one command. To do so execute the following command (clone this repo to make the commands available to you):

bash (macOS/Linux)

release image:
```
./run RunReleaseFromRegistry
```
dev image:
```
./run RunDevFromRegistry
```

Command Prompt (Windows):

release image:
```
.\run.bat RunReleaseFromRegistry
```
dev image:
```
.\run.bat RunDevFromRegistry
```

PowerShell Core (Cross Platform):

release image:
```
.\run.ps1 -RunReleaseFromRegistry $True
```
dev image:
```
.\run.ps1 -RunDevFromRegistry $True
```

Option 2: Start Docker Container With Self-Built Image

To create the Docker image yourself you need to execute these steps:

Clone this GitHub repository to a local folder on your machine.

📝 Tip If you are on Windows you you get an error when cloning the repository stating Filename too long, you need to adjust your git settings: git config --system core.longpaths true
Open the local folder in a terminal window on your machine (or in VS Code).
Build the image with the following command:
- bash (macOS/Linux)
```
./run
```
- Command Prompt (Windows):
```
.\run.bat
```
- PowerShell Core (Cross Platform):
```
.\run.ps1
```

The script will build a Docker image and create a running container from it, on your machine.

Get the Docker Container up-and-running

Regardless of which option you chose, you should now see the Docker container up and running. In case you are using VS Code, open the command palette (Windows: Ctrl+Shift+P ; Mac: Cmd+Shift+P) and select the Remote Containers: Attach to Running Container... command:

📝 Tip - Don't forget to install the Dev Containers extension in VS Code

Then look for the container by name (btp-setup-automator) and selecting it:

You may see a message in VS Code informing you about the installation of some VS Code mechanisms into the container (to support the attachment to the remote container) and may have to wait a minute or two for this to complete.

Using the Setup Automator

You can run the container directly via the terminal or within VS Code, modify use case file and parameter file or supply externally available use case and parameter file.

Read the detailed instructions on how to setup your SAP BTP account for a use case with the btp-setup-automator.

With VS Code

If you want a more detailed walk-through guiding you through the first steps with the btp-setup-automator and VS Code, then this video on YouTube is worth a look:

From a terminal

You can also attach to the running container and execute a shell in there:

docker exec -it btp-setup-automator bash

You'll be placed in a new Bash shell inside the container, with access to all the tools:

; docker exec -it btp-setup-automator bash
bash-5.1$ ls
LICENSE  LICENSES  README.md  btpsa  config  docs  generator  libs  parameters.json  tests  usecases
bash-5.1$ btp
Welcome to the SAP BTP command line interface (client v2.24.0)

Usage: btp [OPTIONS] ACTION GROUP/OBJECT PARAMS

CLI server URL:                    not set
User:                              not set
Configuration:                     /home/user/.config/btp/config.json

You are currently not logged in.

Tips:
    To log in to a global account of SAP BTP, use 'btp login'. For help on login, use 'btp help login'.
    To display general help, use 'btp help'.

bash-5.1$

Known Issues

Checkout the issues section in this repo for known and current issues.

How to get Support?

❓ - If you have question you may peruse the Frequently Asked Questions document. If you did not find your questions answered there you can ask a question in SAP Community.

🐛 - If you find a bug, feel free to create an bug report.

🚀 - If you have an idea for improvement or a feature request, please open feature-request.

Contributions

Checkout the CONTRIBUTING.md file for more details on how to contribute to this open source project.

📝 Tip - If you provide a pull request make sure that the basis of your work as well as the target for your pull request is the dev branch of this repository.

Code of conduct

Checkout the CODE_OF_CONDUCT.md file for more details on the code of conduct for this open source project.

nimble-123 / btp-setup-automator