diff --git a/.devcontainer/dev/devcontainer.json b/.devcontainer/dev/devcontainer.json new file mode 100644 index 00000000..26e8ffe4 --- /dev/null +++ b/.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" + } +} \ No newline at end of file diff --git a/.devcontainer/stable/devcontainer.json b/.devcontainer/stable/devcontainer.json new file mode 100644 index 00000000..b6c459df --- /dev/null +++ b/.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" + } +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json index 93f202a8..4f2c9f70 100644 --- a/.vscode/settings.json +++ b/.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, diff --git a/docs/BASIC_SETUP.md b/docs/BASIC_SETUP.md index b1dfd6e3..6537b883 100644 --- a/docs/BASIC_SETUP.md +++ b/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: diff --git a/docs/README.md b/docs/README.md index 9ff26d15..fda6be1a 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/pics/command-palette-devcontainer.png b/docs/pics/command-palette-devcontainer.png new file mode 100644 index 00000000..5cb313c4 Binary files /dev/null and b/docs/pics/command-palette-devcontainer.png differ diff --git a/docs/pics/devcontainer-config-options.png b/docs/pics/devcontainer-config-options.png new file mode 100644 index 00000000..f41a553c Binary files /dev/null and b/docs/pics/devcontainer-config-options.png differ diff --git a/docs/pics/open-in-remote-window.png b/docs/pics/open-in-remote-window.png new file mode 100644 index 00000000..e573f97c Binary files /dev/null and b/docs/pics/open-in-remote-window.png differ