doc: Client Documentation

Added more comprehensive documenation for download-vs-code.sh script.

README.md

@@ -1,12 +1,14 @@
 # DL VS Code Server
 
-This script downloads a tar of VS Code Server, then extracts it to a location
-expected by VS Code clients. The intention of this script is to pre-install
-the server during image build. This helps ensure, in certain scenarios,
-that the server is there when internet is not; while still allowing your VS
-Code client to connect to it.
+This script downloads a tar of VS Code Server/CLI, then extracts it to a
+location expected by tunnels made by VS Code clients.
 
-To get the latest version of VS COde server pre-installed, then re-run the
+The intention of this script is to pre-install the VS Code binary during
+container image build. This helps ensure, in certain scenarios, that the binary
+is there when internet is not; while still allowing your VS Code client to
+tunnel to the container.
+
+When the VS Code binary is out-of-date, to get the latest version, re-run the
 script.
 
 ## Background
@@ -23,26 +25,52 @@ script at [b01/download-vs-code-server.sh]
 
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/b01/dl-vscode-server/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/b01/dl-vscode-server/tree/main)
 
-## How To Use
+## How To Install
 
-You only need to download the script `download-vs-code-server.sh` and run it.
+### Shell
+```shell
+curl -L https://raw.githubusercontent.com/b01/dl-vscode-server/main/download-vs-code-server.sh | bash -s -- "linux"
+```
 
-`download-vs-code-server.sh <PLATFORM> <ARCH>`
+### Docker
 
-Example:
+```dockerfile
+ADD --chmod=777 \
+    https://raw.githubusercontent.com/b01/dl-vscode-server/updates-2024-05-16-01/download-vs-code.sh \
+    .
 
-```shell
-curl -L https://raw.githubusercontent.com/b01/dl-vscode-server/main/download-vs-code-server.sh | bash -s -- "linux"
+# Install VS Code Server and Requirements
+RUN ./download-vs-code.sh "linux" "x64" --alpine
 ```
 
-### Arguments
+## How To Use
+
+`download-vs-code.sh [options] <PLATFORM> [<ARCH>]`
+
+### Example:
+
+download-vs-code.sh \"linux\" \"x64\" --alpine
+
+### Options
+
+`--insider`
+Switches to the pre-released version of the binary chosen (server or
+CLI).
+
+`--dump-sha`
+Will print the latest commit sha for VS Code (server and CLI are current
+synced and always the same)
+
+`--cli`
+Switches the binary download VS Code CLI.
 
-**PLATFORM** - Currently `linux`, `alpine`, and any others Microsoft supports.
+`--alpine`
+Only works when downloading VS Code Server, it will force PLATFORM=linux and
+ARCH=alpine, as the developers deviated from the standard format used for all
+others.
 
-**ARCH** - Optional, will default to `uname -m`, which will map to a value
-that Microsoft expects, so for, aarch64 => arm64, x86_64 => x64, and so on.
-`armv7l` will map to armhf. It best to specify the arch if you know it.
-If you supply a value, that will be used without being mapped.
+`-h, --help`
+Print this usage info
 
 ---
 

docs/how-to-test.md

@@ -4,6 +4,31 @@ The VS Code Server has a lot of location where it needs to reside for the many
 different type of DevContainer setups. These instructions should provide how
 to verify the script still works in those scenarios. Each heading below
 represents a different scenario.
+
+## VS Code Download URL Format
+
+These URLS helped derived format to remove guessing where to download.
+
+### CLI URLs
+```shell
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-linux-x64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-alpine-x64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-darwin-x64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-darwin-arm64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-win32-x64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-win32-arm64/stable
+```
+
+### Server
+
+```shell
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-linux-x64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-darwin-x64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-darwin-arm64/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-linux-alpine/stable
+# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-win32-x64/stable
+```
+
 ## Pre-requisites
 
 1. Start Docker Desktop (or equivalent) if it has not been started already.
@@ -32,4 +57,3 @@ this example):
 ## Web VSCode to Remote Container
 
 Untested.
-

download-vs-code.sh

@@ -21,7 +21,36 @@
 # IN THE SOFTWARE.
 
 set -e
+usage="
+This script downloads a tar of VS Code Server/CLI, then extracts it to a
+location expected by tunnels made by VS Code clients.
 
+download-vs-code.sh [options] <PLATFORM> [<ARCH>]
+
+Example:
+  download-vs-code.sh \"linux\" \"x64\" --alpine
+
+Options
+
+--insider
+    Switches to the pre-released version of the binary chosen (server or
+    CLI).
+
+--dump-sha
+    Will print the latest commit sha for VS Code (server and CLI are current
+    synced and always the same).
+
+--cli
+    Switches the binary download VS Code CLI.
+
+--alpine
+    Only works when downloading VS Code Server, it will force PLATFORM=linux and
+    ARCH=alpine, as the developers deviated from the standard format used for
+    all others.
+
+-h, --help
+    Print this usage info.
+"
 # Get the latest VS Code commit sha.
 get_latest_release() {
     platform=${1}
@@ -120,6 +149,10 @@ while [ ${#} -gt 0 ]; do
         --alpine)
             IS_ALPINE=1
             ;;
+        -h|--help)
+            echo "${usage}"
+            exit 0
+            ;;
         -*|--*)
             echo "Unknown option ${op}"
             exit 1
@@ -170,6 +203,7 @@ if [ "${BIN_TYPE}" = "server" -a ${IS_ALPINE} -eq 1 ]; then
     ARCH="alpine" # Alpine is NOT an Arch but a flavor of Linux, oh well.
 fi
 
+# We hard-code this because all but a few options returns a 404.
 commit_sha=$(get_latest_release "win32" "x64" "${BUILD}")
 
 if [ -z "${commit_sha}" ]; then
@@ -187,18 +221,6 @@ echo "attempting to download and pre-install VS Code ${BIN_TYPE} version '${comm
 options="${BIN_TYPE}-${PLATFORM}-${ARCH}"
 archive="vscode-${options}.tar.gz"
 
-# URLs that helped derived format:
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-linux-x64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-alpine-x64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-darwin-x64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-darwin-arm64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-win32-x64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/cli-win32-arm64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-linux-x64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-darwin-x64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-darwin-arm64/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-linux-alpine/stable
-# https://update.code.visualstudio.com/commit:b58957e67ee1e712cebf466b995adf4c5307b2bd/server-win32-x64/stable
 # Download VS Code tarball to the current directory.
 url="https://update.code.visualstudio.com/commit:${commit_sha}/${options}/${BUILD}"
 printf "%s" "downloading ${url} to ${archive} "

test/alpine-musl/Dockerfile

@@ -30,7 +30,7 @@ RUN apk --no-progress --purge --no-cache upgrade \
 && apk --no-progress --purge --no-cache upgrade \
  && rm -vrf /var/cache/apk/*
 
-COPY  --chmod=+x test/alpine/start.sh /usr/local/bin
+COPY  --chmod=+x test/alpine-musl/start.sh /usr/local/bin
 
 HEALTHCHECK --interval=5m --timeout=3s \
   CMD echo "healthy" || exit 1

test/debian/Dockerfile

@@ -29,7 +29,7 @@ RUN apt-get -qq update -qq && apt-get -qq install -qq \
 && apt-get -qq update \
  && rm -rf /var/lib/apt/lists/*
 
-COPY --chmod=+x test/alpine/start.sh /usr/local/bin
+COPY --chmod=+x test/debian/start.sh /usr/local/bin
 
 HEALTHCHECK --interval=5m --timeout=3s \
   CMD echo "healthy" || exit 1