Introduction of devcontainer and GitHub Codespaces for easier executi…

…on of btpsa (#429)

* setup GitHub CodeSpace definition

* rework of codespaces

* enhancement of documentation

.devcontainer/dev/devcontainer.json

@@ -0,0 +1,36 @@
+// For format details, see https://aka.ms/devcontainer.json.
+{
+    "name": "BTP Setup Automator (Dev)",
+    "image": "ghcr.io/sap-samples/btp-setup-automator:latest",
+    "customizations": {
+        "vscode": {
+            "settings": {
+                "python.defaultInterpreterPath": "/usr/local/bin/python3",
+                "python.linting.enabled": true,
+                "python.formatting.provider": "black",
+                "python.linting.flake8Enabled": true,
+                "python.linting.flake8Args": [
+                    "--ignore=E501,F405,W504"
+                ],
+                "python.linting.pylintEnabled": false
+            },
+            "extensions": [
+                "ms-python.python",
+                "ms-python.vscode-pylance"
+            ]
+        },
+        "codespaces": {
+            "openFiles": [
+                "parameters.json"
+            ]
+        }
+    },
+    "remoteUser": "user",
+    "postCreateCommand": "cd /home/user && echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.profile && pip install flake8 black && source ~/.profile",
+    "workspaceFolder": "/home/user",
+    "hostRequirements": {
+        "cpus": 2,
+        "memory": "4gb",
+        "storage": "32gb"
+    }
+}

.devcontainer/stable/devcontainer.json

@@ -0,0 +1,36 @@
+// For format details, see https://aka.ms/devcontainer.json.
+{
+    "name": "BTP Setup Automator (Stable)",
+    "image": "ghcr.io/sap-samples/btp-setup-automator:latest",
+    "customizations": {
+        "vscode": {
+            "settings": {
+                "python.defaultInterpreterPath": "/usr/local/bin/python3",
+                "python.linting.enabled": true,
+                "python.formatting.provider": "black",
+                "python.linting.flake8Enabled": true,
+                "python.linting.flake8Args": [
+                    "--ignore=E501,F405,W504"
+                ],
+                "python.linting.pylintEnabled": false
+            },
+            "extensions": [
+                "ms-python.python",
+                "ms-python.vscode-pylance"
+            ]
+        },
+        "codespaces": {
+            "openFiles": [
+                "parameters.json"
+            ]
+        }
+    },
+    "remoteUser": "user",
+    "postCreateCommand": "cd /home/user && echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.profile && pip install flake8 black && source ~/.profile",
+    "workspaceFolder": "/home/user",
+    "hostRequirements": {
+        "cpus": 2,
+        "memory": "4gb",
+        "storage": "32gb"
+    }
+}

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-    "python.pythonPath": "/usr/local/bin/python3",
+    "python.defaultInterpreterPath": "/usr/local/bin/python3",
     "python.linting.enabled": true,
     "python.formatting.provider": "black",
     "python.linting.flake8Enabled": true,

docs/BASIC_SETUP.md

@@ -18,14 +18,44 @@ In case you are new to the containers topic, we **strongly recommend** that you
 
 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)
+### Option 1: Start the btpsa via Dev Container (recommended)
 
-This is the fastest way to use the `btp-setup-automator`. We offer two images for the `btp-setup-automator`:
+We provide two configurations for Dev Containers to start the `btp-setup-automator` based on the two pre-built images we serve on GitHub:
 
-- The **release** image: This is a stable version of the `btp-setup-automator` and corresponds to the latest release visible on the [release section](https://github.com/SAP-samples/btp-setup-automator/releases) of the repository. The corresponding code is taken from the [`main branch`](https://github.com/SAP-samples/btp-setup-automator/tree/main) of the repository.
+- The **release**/**stable** image: This is a *stable* version of the `btp-setup-automator` and corresponds to the latest release visible on the [release section](https://github.com/SAP-samples/btp-setup-automator/releases) of the repository. The corresponding code is taken from the [`main branch`](https://github.com/SAP-samples/btp-setup-automator/tree/main) 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`](https://github.com/SAP-samples/btp-setup-automator/tree/dev) 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.
+To start a Dev Container in VS Code the easiest way is to click on the "Open a remote Window" button in the footer of VS Code:
+
+![open in remote window](pics/open-in-remote-window.png)
+
+This opens the command palette. Select `Reopen in Container` in the Dev Container section:
+
+![reopen in container](pics/command-palette-devcontainer.png)
+
+Select the configuration you want to use (*stable* or *dev*):
+
+![devcontainer config options](pics/devcontainer-config-options.png)
+
+VS Code will reopen in the Dev Container and you can start using the  `btp-setup-automator`.
+
+> 📝 Tip - You can also use the VS Code command palette (in the menu "View" select "Command Palette" or press the key combination `Ctrl+Shift+P` for Windows or `Cmd+Shift+P` for Mac) and use the "Dev Container: Reopen in Container" option from there.
+
+#### Alternative GitHub Codespaces
+
+Defining Dev Container configurations opens up the option to use [GitHub Codespaces](https://docs.github.com/en/codespaces) as you execution environment for the `btp-setup-automator`.
+
+To open the btpsa in GitHub Codespaces use the badges provided on the [main page](https://github.com/SAP-samples/btp-setup-automator) of the repository.
+
+> ⚠ NOTE: Cost might occur on your personal or organizational account when using GitHub Codespaces. You find more information on that topic [here](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces).
+
+In case you are using SSO as login option when execution use cases, be aware that there might be issues when it comes to [forwarded ports](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports) depending on your organizational settings.
+
+### Option 2: Start Docker Container with Pre-Built Images via scripts
+
+As an alternative to Dev Containers you can also directly spin up the `btpsa` container via Docker CLI or via `run` scripts that we provide. This sections guides you through this setup.
+
+To leverage the Docker CLI, 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:
 
@@ -111,7 +141,7 @@ You can also use the provided `run` files to pull the image from the registry an
       .\run.ps1 -RunDevFromRegistry $True
       ```
 
-### Option 2: Start Docker Container With Self-Built Image
+### Option 3: Start Docker Container With Self-Built Image
 
 To create the Docker image yourself you need to execute these steps:
 

docs/README.md

@@ -1,30 +1,35 @@
-# Detailed walk-though
-
-In case you are using VS Code (recommended), you need to open the Command Palette (in the menu "View" select "Command Palette") or press the key combination `Ctrl+Shift+P` (Windows) or `Cmd+Shift+P` (Mac). Then enter the command:
-
-```text
-Remote-Containers: Attach to Running Container
-```
-
-![command in VS Code to attach it to a running container](pics/quick-guide-step00.png)
-
-Now you should see the running container. Click on it, and a new window will pop-up with the content of the Docker container.
-
-![select running container in VS Code](pics/quick-guide-step01.png)
-
-You might have to select folder with the content in navigation panel of VS Code via `Open Folder`:
-
-![open folder](pics/quick-guide-step02.png)
-
-Select the `/home/user` folder:
-
-![select folder](pics/quick-guide-step03.png)
-
-You can also open a new terminal in the container via the menu `Terminal` - `New Terminal`. This will open an `ash` shell.
-
+# Detailed walk-through
+
+To edit the `parameters.json` as well as the `usecase.json` files and to execute them you must connect to the `btp-setup-automator` container.
+
+In case you are using VS Code (recommended), you have the following options:
+
+* Use the [Dev Container](./BASIC_SETUP.md#option-1-start-the-btpsa-via-dev-container-recommended) that opens VS Code inside of the container.
+* Attach to a running container (e.g. when [started via Docker CLI](./BASIC_SETUP.md#option-2-start-docker-container-with-pre-built-images-via-scripts))need to open the Command Palette (in the menu "View" select "Command Palette") or press the key combination `Ctrl+Shift+P` (Windows) or `Cmd+Shift+P` (Mac). Then enter the command:
+
+   ```text
+   Remote-Containers: Attach to Running Container
+   ```
+
+   ![command in VS Code to attach it to a running container](pics/quick-guide-step00.png)
+
+   Now you should see the running container. Click on it, and a new window will pop-up with the content of the Docker container.
+
+   ![select running container in VS Code](pics/quick-guide-step01.png)
+
+   You might have to select folder with the content in navigation panel of VS Code via `Open Folder`:
+
+   ![open folder](pics/quick-guide-step02.png)
+
+   Select the `/home/user` folder:
+
+   ![select folder](pics/quick-guide-step03.png)
+
+After connecting to the container, open a new terminal in the container via the menu `Terminal` - `New Terminal`. This will open an `ash` shell.
+
 ![open new terminal](pics/quick-guide-step04.png)
 
-The last step is to run the main script `btpsa` with the following command:
+The last step is to run the main script `btpsa` via the command:
 
 ```bash
 ./btpsa