diff --git a/tools/README.md b/tools/README.md index 39eb6ce..ff00584 100644 --- a/tools/README.md +++ b/tools/README.md @@ -20,3 +20,115 @@ Example: The caller is dumped in as the root user so they can manipulate the image runtime with package installation, removal, etc. + +## Basic Usage + +NOTE: The `vs-images.sh` script is presently setup to operate from within its home directory. + +The `vs-images.sh` operates with a series of options and some commands to perform, the most basic of which is the +`help` command: + + $ ./vs-image.sh help + ./vs-image.sh + + may be one or more of the following: + --docker 'docker' binary to use + --github-user Specify the github user or organization to use - Default: "vegastrike" + --github-workflow Specify the github workflow to use for images - Default: "../.github/workflows/gh-actions-pr.yml" + --git-branch Specify which Git Branch to use - Default: "master" + --image-base Specify which Vega Strike Image to use + --image-tag Specify tag name to use - Default: "vs_tester:latest" + --yq 'yq' binary to use + + may be one of the following: + help Show this dialog + show-ci-images Show image targets used by the CI systems + show-images List Images used by the Vega Strike CI system available locally + build-base Build the base image (CI Image) + build Build the image (Dev Image) + run Run the image + + + Git Branch: "master" + GitHub Username: "vegastrike" + GitHub Workflow: "../.github/workflows/gh-actions-pr.yml" + Image Base: "" + Image Tag: "vs_tester:latest" + +### Show CI Images + +The `show-ci-images` command is used to analyze the GitHub Actions Workflow and output the images that would be generated. +These are used as the base images for the VS repositories and also the Dockerfile provided here. + +This command is augmented by the `yq` command which is used to parse the GitHub Actions Workflows that are in YAML format. +As part of its operation it checks if the `yq` command specified is the one expected so that it knows the operation will +work properly. Unfortunately, different `yq` commands have different options. + +### Show Images + +The `show-images` command is used to see what base images are available locally by examining the Docker Images cache. + +### Build Base + +The `build-base` command is used to build an image that would be used by the CI tooling. +It takes a single option (`--image-base`) to identify which CI Image to build. + +### Build + +The `build` command is used to build the testing Dockerfile that is loaded with the VS code. It uses most of the options to +provide its functionality. + +### Run + +The `run` command is used to start up the testing Dockefile to enable the user to test out the environment. +It simply needs the `--image-tag` option to identify the image to start and is a simple wrapper around the `docker run` +command to make it easy to access the Vega Strike Build Environments. + +## Options + +The script takes a number of different options. Many commands will output their view of the various options prior to the +command being run for easy diagnosis. + +### --docker + +The `--docker` option is used to specify the binary for the `docker` command and is used to list images, build images, and run images. + +Default: `docker` + +### --github-user + +The `--github-user` option is used to specify the GitHub User or Organization from which to pull the Vega Strike Engine Source Code. + +Default: `vegastrike` + +### --github-workflow + +The `--github-workflow` option is used to search for the possible Base Images to use. The value values are in this repositories `.github/workflows` +directory. + +Default: `../.github/workflows/gh-actions-pr.yml` + +### --git-branch + +The `--git-branch` option is used to determine which branch in the repository to checkout. + +Default: `master` + +### --image-base + +The `--image-base` option is used to specify which Vega Strike Docker Hub Docker Image to use as the base. However it pulls from the local system only. +This option contributes to the image name to be used in the format: + + vegastrike/vega-strike-build-env: + +Following the same design as the Vega Strike CI system. + +### --image-tag + +The `--image-tag` option is used to give the Dev Image a name for easy access. This should be a fully qualified name (name + tag) as opposed to just a name +in order to prevent mismatches since the `latest` tag would automatically be assumed. + +### --yq + +The `--yq` option is used to specify the YQ binary to be used for parsing the GitHub Workflow files. +This script is designed to use https://github.com/mikefarah/yq for YAML parsing. diff --git a/tools/vs-image.sh b/tools/vs-image.sh index 4caa886..b60f104 100755 --- a/tools/vs-image.sh +++ b/tools/vs-image.sh @@ -57,14 +57,14 @@ function isYqInstalled() { return ${result} } -# Command: CMD_SHOW_IMAGES -function printImageNames() { +# Command: CMD_SHOW_RELEASE_IMAGES +function printImageReleaseNames() { isYqInstalled if [ $? -ne 0 ]; then return 1 fi - echo "The following images are available:" + echo "The following images targets are available:" IFS=" " for IMAGE_NAME in $(${YQ} eval '.jobs.build.strategy.matrix.FROM*' ${GITHUB_WORKFLOW} | grep -v ^# | cut -f 2 -d \' | sort) @@ -74,6 +74,35 @@ function printImageNames() { return 0 } +# Command: CMD_SHOW_IMAGES +function printImageLocalNames() { + isYqInstalled + if [ $? -ne 0 ]; then + return 1 + fi + + echo "The following images are available locally:" + IFS=" +" + for IMAGE_NAME in $(docker images | grep ^vegastrike | tr -s ' ' ';' | cut -f 2 -d ';' | sort) + do + printf "\t${IMAGE_NAME}\n" + done + return 0 +} + +# Command: CMD_BUILD_BASE_IMAGE +function buildBaseImage() { + local IMAGE_BASE="${1}" + local DOCKER_IMG_NAME="vegastrike/vega-strike-build-env:$(echo "${IMAGE_BASE}" | sed 's/:/_/' | sed 's/\//_/')" + local IS_RELEASE=0 + local MY_OS_NAME="linux" + ${DOCKER} build \ + --build-arg from="${IMAGE_BASE}" \ + --tag "${DOCKER_IMG_NAME}" \ + .. +} + # Command: CMD_BUILD_IMAGE function buildImage() { local IMAGE_BASE="${1}" @@ -107,7 +136,9 @@ function printInfo() { # Variablized commands and argument names CMD_HELP="help" +CMD_SHOW_RELEASE_IMAGES="show-ci-images" CMD_SHOW_IMAGES="show-images" +CMD_BUILD_BASE_IMAGE="build-base" CMD_BUILD_IMAGE="build" CMD_RUN_IMAGE="run" @@ -135,8 +166,10 @@ function printHelp() { echo echo " may be one of the following:" echo " ${CMD_HELP} Show this dialog" - echo " ${CMD_SHOW_IMAGES} List Images used by the Vega Strike CI system" - echo " ${CMD_BUILD_IMAGE} Build the image" + echo " ${CMD_SHOW_RELEASE_IMAGES} Show image targets used by the CI systems" + echo " ${CMD_SHOW_IMAGES} List Images used by the Vega Strike CI system available locally" + echo " ${CMD_BUILD_BASE_IMAGE} Build the base image (CI Image)" + echo " ${CMD_BUILD_IMAGE} Build the image (Dev Image)" echo " ${CMD_RUN_IMAGE} Run the image" echo } @@ -155,8 +188,19 @@ do printInfo exit 0 ;; + "${CMD_SHOW_RELEASE_IMAGES}") + printImageReleaseNames "${YQ}" + processOpErrors $? + exit $? + ;; "${CMD_SHOW_IMAGES}") - printImageNames "${YQ}" + printImageLocalNames "${YQ}" + processOpErrors $? + exit $? + ;; + "${CMD_BUILD_BASE_IMAGE}") + printInfo + buildBaseImage "${IMAGE_BASE}" processOpErrors $? exit $? ;;