#584: improved doc, use Docker Desktop for Windows (#594)

documentation/cli.asciidoc

@@ -37,6 +37,17 @@ Every commandlet takes the following generic arguments:
 |`-q` or `--quiet` |be quiet and avoid output.
 |=======================
 
+=== Command-wrapper
+For many commandlets the `devon` command acts as a wrapper.
+Similar to `mvnw` or `gradlew` you can use it as a proxy command.
+Therefore `devon mvn clean install` will be the same as `mvn clean install`.
+The benefit when using `devon` as wrapper is that it will even work when the command (`mvn`, `node`, `npm`, etc.) is not on your `PATH` variable or even not yet installed.
+We see the main benefit in this for writing portable scripts that you may commit to your git repository and that will then run everywhere and will lazily install the required tools on the fly.
+In your daily usage you can and surely should avoid to always type `devon` as prefix to every command.
+However, when you automate and want to avoid "command not found" errors, you can simply prefix the command with `devon`.
+
+=== Commandlet overview
+
 The following commandlets are currently available:
 
 * link:build.asciidoc[build]
@@ -59,4 +70,4 @@ The following commandlets are currently available:
 * link:release.asciidoc[release]
 * link:sonar.asciidoc[sonar]
 * link:vscode.asciidoc[vscode]
-* link:yarn.asciidoc[yarn]
+* link:yarn.asciidoc[yarn]

documentation/docker.asciidoc

@@ -14,4 +14,61 @@ The arguments (`devon docker «args»`) are explained by the following table:
 |*Argument(s)*             |*Meaning*
 |`setup`                   |setup Docker (install and verify) as per above flow.
 |`«args»`                  |call docker with the specified arguments. Call `docker help` for details or use docker directly as preferred." (`«args»`)
-|=======================
+|=======================
+
+== setup
+The `docker` commandlet will install `docker` automatically.
+Please note that besides the sandbox concept of devonfw-ide this is a global installation on your system.
+When uninstalling devonfw-ide, you may have to manually uninstall `docker` and `kubernetes` if you do not need it anymore.
+
+=== requirements
+Running docker and especially link:kubectl.asciidoc[kubernetes] on your machine in the background will require quite some resources.
+This will allocate at least 2GB of additional RAM.
+
+You will need at least 8GB of total RAM while we recommend to use 16GB+.
+
+You may also tune and scale it to your needs.
+When using Docker Desktop (Windows or MacOS) simply go to the https://docs.docker.com/docker-for-windows/#resources[resources tab in the settings].
+It will depend on your usage frequency if you want to have it running in the background all the time.
+This is a balance between resource utilization and convenience.
+If you use docker and kubernetes on your local machine on a daily basis this makes sense.
+
+In case you only use docker rarely, you can save resources by stopping it when not needed after it has been installed.
+
+=== Windows and Mac
+To enable or disable autostart, you can launch `Docker Desktop` on Windows or MacOS got to the `Preferences` (gear icon in the title bar). Then in the `General` tab you can check or uncheck the option `Start Docker Desktop when you login` (see also https://docs.docker.com/docker-for-windows/#general[here]). When autostart is disabled and you launch `Docker Desktop` it will notice and ask your to start the service or do this automatically for you.
+On Windows you can also manually tweak this:
+
+* Hit `[windows][r]`
+* Enter `services.msc`
+* Confirm with `OK`
+* In the services app search for the `Docker Desktop Service` in the list and select it.
+* Now you can start or stop the service by clicking on the according link text.
+* Also when right clicking on `Docker Desktop Service` and selecting `Options` from the context-menu, you can change the start type to `automatic` or `manual`.
+
+==== Mac A1
+In case you have a new Mac with A1 CPU, we automatically download and install the according ARM version of `Docker Desktop for Mac`.
+However, if you use docker and search for images you may end up with errors like:
+```
+docker: no matching manifest for linux/arm64/v8 in the manifest list entries.
+```
+
+So with A1 CPU you may need to add `--platform linux/x86_64` as option to your docker command to find the expected container image.
+
+=== Linux
+There is no Docker Desktop for Linux.
+As docker initially comes from the Linux world, it is easy to set it up on a Linux machine and use it from the commandline.
+Therefore we do not install a GUI for you in case you are a Linux user.
+In case you need a GUI for docker and kubernetes on Linux you can choose from the following options:
+
+* https://dockstation.io/[DockStation]
+* https://portainer.io/[Portainer]
+* https://kitematic.com/[Kitematic]
+* https://shipyard-project.com/[Shipyard]
+
+== usage
+Once installed via setup, you can run docker directly from any shell of your OS directly.
+Run `docker help` to get started and use the online documentations and resources on the web to get familiar with docker.
+It is not our intention to repeat this here.
+
+Please note that the `docker` commandlet is a link:cli.asciidoc#command-wrapper[command wrapper].

documentation/kubectl.asciidoc

@@ -16,3 +16,16 @@ The arguments (`devon kubectl «args»`) are explained by the following table:
 |`setup`                   |setup Kubernetes (install and verify) as per above flow.
 |`«args»`                  |call kubectl with the specified arguments. Call `kubectl help` for details or use kubectl directly as preferred.
 |=======================
+
+== setup
+Please note that on Windows and MacOS `kubernetes` support comes together with `Docker Desktop` that is installed via link:docker.asciidoc[docker] commandlet.
+When you have installed and launched `Docker Desktop`, you can once https://docs.docker.com/desktop/kubernetes/#enable-kubernetes[enable kubernetes in the Preferences].
+
+On Linux however, kubernetes is installed separately by this commandlet.
+
+== usage
+Once installed via setup, you can run `kubectl` directly from any shell of your OS directly.
+Run `kubectl help` to get started and use the online documentations and resources on the web to get familiar with kubernetes.
+It is not our intention to repeat this here.
+
+Please note that the `kubectl` commandlet is a link:cli.asciidoc#command-wrapper[command wrapper].

scripts/src/main/resources/scripts/command/docker

@@ -19,33 +19,19 @@ function doSetup() {
   if doIsDockerInstalled 
   then
     doEcho "docker is already installed at $(command -v docker)"
+    docker version
   else
+    doRequireNotBatch
     #Start setup
     if doIsWindows
     then
-      doRequireWsl
-      # Verify if docker is installed on Windows Subsystem for Linux(WSL)
-      docker_win_version=$(wsl docker version 2>/dev/null)
-      if [[ $docker_win_version == *"Client:"* ]]
-      then
-        if [ "${1}" = "setup" ]
-        then
-          doEcho "Docker already installed on WSL."
-          wsl docker version
-        fi
-        if [[ $docker_win_version != *"Server:"* ]]
-        then
-          doEcho "Please start Docker engine on WSL."
-        fi
-      else
-        doRequireNotBatch
-        doEcho "Installing Docker on WSL..."
-        # Install Docker on WSL
-        doRunCommand "wsl bash ../scripts/setup-docker"
-      fi
+      local downloadUrl="https://desktop.docker.com/win/stable/amd64/Docker%20Desktop%20Installer.exe"
+      doEcho "Downloading Docker Desktop for Windows..."
+      doDownload "${downloadUrl}" "Docker_Desktop_Installer.exe"
+      doEcho "Installating Docker Desktop for Windows..."
+      doRunCommand "${DEVON_DOWNLOAD_DIR}/Docker_Desktop_Installer.exe"
     elif doIsMacOs
     then
-      doRequireNotBatch
       local downloadUrl
       local arch
       arch="$(uname -m)"
@@ -66,29 +52,18 @@ function doSetup() {
       doRunCommand "hdiutil attach -quiet -nobrowse -mountpoint '${mount_dir}' '${DEVON_DOWNLOAD_DIR}/Docker.dmg'"
       doRunCommand "cp -a '${mount_dir}'/*.app /Applications/"
       doRunCommand "hdiutil detach -force '${mount_dir}'"
-      read -r -p "Docker Desktop has been installed on your Mac. In order to use it properly you need to go to Launchpad and start the Docker app.Press enter to confirm and continue" answer
     else
       doFail "Sorry, docker-installation support is not yet implemented for your OS. Please install manually or help devonfw-ide to support it for your OS by contributing a pull-request."
     fi
+    read -r -p "Docker Desktop has been installed. Please read https://github.com/devonfw/ide/blob/master/documentation/docker.asciidoc#setup for enabling kubernetes and further important details. Press enter to continue" answer
   fi
 }
 
 # Call Docker with specified arguments.
 function doRun() {
   doSetup
-  # Run docker command if installed.
-  if doIsDockerInstalled
-  then
-    doEcho "Running: docker ${*}"
-    docker "${@}"
-  # Run docker command on Windows WSL if installed.
-  elif doIsWindows
-  then
-    doEcho "Running: docker ${*} on WSL."
-    wsl docker "${@}"
-  else
-    doFail "Docker could not be found."
-  fi
+  doEcho "Running: docker ${*}"
+  docker "${@}"
 }
 
 # OS independent check if docker is installed.
@@ -101,16 +76,6 @@ function doIsDockerInstalled() {
   fi
 }
 
-# Checks if docker is installed on Windows Subsystem for Linux(WSL)
-function doIsDockerInstalledOnWsl() {
-  if wsl command -v docker &> /dev/null
-  then
-    return
-  else   
-    return 255  
-  fi   
-}
-
 # CLI
 case ${1} in 
 "help" | "-h")
@@ -119,12 +84,12 @@ case ${1} in
   echo "Arguments:"
   echo " setup                    setup docker on your machine (global installation)."
   echo " «args»                   call docker with the specified arguments. Call docker help for details or use docker directly as preferred."
-  echo  
+  echo
 ;;
 "setup" | "s" | "")
   doSetup setup
 ;;
 *)
    doRun "${@}"
 ;;
-esac
+esac

scripts/src/main/resources/scripts/command/kubectl

@@ -27,25 +27,10 @@ function doSetup() {
   fi
   if doIsWindows
   then
-    doRequireWsl
-    # Check if Kubernetes is already installed on WSL
-    if doIsKubernetesInstalledOnWsl
-    then
-      if [ "${1}" = "setup" ]
-      then
-        echo Kubernetes is already installed on WSL and ready to use. devonfw-ide did not make any changes.
-        wsl kubectl version
-      fi
-    else
-      doRequireNotBatch
-      doEcho "Installing Kubernetes on WSL..."
-      # Install Kubernetes on WSL
-      doRunCommand "wsl bash ../scripts/setup-kubernetes"
-    fi
+    doDevonCommand docker -q setup
   elif doIsMacOs
   then
     doDevonCommand docker -q setup
-    read -r -p "In order to activate kubernetes, open Docker Desktop and enable kubernetes. For details see https://docs.docker.com/desktop/kubernetes/#enable-kubernetes - Press enter when you have enabled kubernetes." answer
   else
     doFail "Sorry, kubernetes-installation support is not yet implemented for your OS. Please install manually or help devonfw-ide to support it for your OS by contributing a pull-request."
   fi
@@ -55,19 +40,8 @@ function doSetup() {
 # Call Kubernetes with specified arguments
 function doRun() {
   doSetup
-  # Run Kubernetes command if installed on Windows.
-  if doIsKubernetesInstalled
-  then
-    doEcho "Running: kubectl ${*}"
-    kubectl "${@}"
-  # Run Kubernetes command on WSL if installed on WSL.
-  elif doIsWindows
-  then
-    doEcho "Running: kubectl ${*} on WSL."
-    wsl kubectl "${@}"
-  else
-    doFail "Kubernetes (kubectl) could not be found."
-  fi
+  doEcho "Running: kubectl ${*}"
+  kubectl "${@}"
 }
 
 # OS independent check if Kubernetes is installed.
@@ -80,16 +54,6 @@ function doIsKubernetesInstalled() {
   fi
 }
 
-# Checks if Kubernetes is installed on Windows Subsystem for Linux(WSL)
-function doIsKubernetesInstalledOnWsl() {
-  if wsl command -v kubectl &> /dev/null
-  then
-    return
-  else
-    return 255
-  fi
-}
-
 # CLI
 case ${1} in 
 "help" | "-h")
@@ -104,6 +68,6 @@ case ${1} in
   doSetup setup
 ;;
 *)
-   doRun "${@}"
+  doRun "${@}"
 ;;
 esac