BASIC_SETUP.md

Basic setup

Pre-requisites

To use the btp-setup-automator, 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 recommend 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"

⚠ NOTE: If you are running on an ARM based platform like a Mac M1 or M2 and are facing issues with the image, add the --platform linux/amd64 option to the docker container run command. The image we provide is built for linux/amd64 and due to some implicit dependencies we cannot perform a built for linux/arm64 with the alpine linux as base image.

Here is 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.

What's next?

You have now successfully setup your environment and are good to go and start with executing a sample setup of an SAP BTP account. Now let us get an overview what we can do here.