feat: Optimized documentation and feature utils

Added template for new features

Author: dploeger

README.md.gotmpl

@@ -283,14 +283,24 @@ environment variable in the docker-compose file. Then you can debug with the run
 
 ## Development
 
-*CloudControl* supports a decoupled development of features and flavours. If you're missing something, just fork this
-repository, create a subfolder for your new feature under "features" and add these files:
+*CloudControl* supports a decoupled development of features and flavours.
+
+### Features
+
+If you're missing a feature, just fork this repository, copy the feature template from features/.template into a
+new subfolder, check out the comments in the example files, and modify them to your needs.
+
+These files make up a feature:
 
 * `feature.yaml`: A descriptor for your feature with a title, a description and configuration notes
 * `install.sh`: A shell script that is run by CloudControlCenter and should install everything you need
   for your new feature
 * `motd.sh`: (optional) If you want to show some information to the users upon login, put them here.
 
+And an optional, but recommended `.goss` folder for [integration testing](#integration-testing).
+
+### Flavours
+
 If you need another flavour (aka cloud provider), add a new subdirectory under "flavour" and add a flavour.yaml describing
 your flavour the same way as a feature. For the rest of the files, please check out existing flavours for details. Please,
 include a sample configuration for your flavour to make it easier for other people to work with it.

assets/feature-installer-utils.sh

@@ -1,4 +1,31 @@
-# Execute a command and if it fails, return its output and exit
+# Set some informative variables
+
+# The flavour we're running on
+FLAVOUR="$(cat /home/cloudcontrol/flavour)"
+export FLAVOUR
+
+# The path to install software binaries to
+BINPATH="/home/cloudcontrol/bin"
+export BINPATH
+
+TEMPDIR=""
+export TEMPDIR
+
+# Prepare feature installation. Will create a temporary directory and change to it
+function prepare {
+  TEMPDIR=$(mktemp -d)
+  cd "${TEMPDIR}" || exit
+}
+
+# Cleanup the previously generated temporary directory
+function cleanup {
+  cd - &>/dev/null || exit
+  rm -rf "${TEMPDIR}"
+}
+
+# Usage: execHandle MESSAGE COMMAND...
+#
+# Output MESSAGE and then execute COMMAND. If it fails, return its output and exit
 function execHandle {
   TITLE=$1
   shift
@@ -38,6 +65,7 @@ function waitForMfaCode {
   echo "[VALID_CODE] Valid code entered. Thank you."
 }
 
+# Get the hardware platform we're on and translate it to the usual platform names used in most software
 function getPlatform {
   if [ "$(uname -m)" == 'aarch64' ]
   then
@@ -50,18 +78,32 @@ function getPlatform {
   fi
 }
 
+# Usage: checkAndCleanVersion VERSION
+#
+# Includes checks for version numbers and removes the "v" prefix from it to have a homogeneous version scheme
+# throughout CloudControl.
 function checkAndCleanVersion {
   VERSION=$1
   if [ "${VERSION:0:1}" == "v" ]
   then
-    echo "[DEPRECATION WARNING] Versions with a \"v\" prefix are deprecated and will be removed in CloudControl 4.0. Please only use versions without the \"v\" prefix. (Got \"${VERSION}\")" >&2
+    echo "[DEPRECATION WARNING] Versions with a \"v\" prefix are deprecated and will be removed in CloudControl 6.0.0 Please only use versions without the \"v\" prefix. (Got \"${VERSION}\")" >&2
     echo "${VERSION/#v/}"
   else
     echo "${VERSION}"
   fi
 }
 
+# Usage: download URL FILENAME
+#
+# Downloads the given URL into the provided FILENAME
+function download {
+  URL=$1
+  FILENAME=$2
+  execHandle "Downloading ${FILENAME} from ${URL}" curl -f -s -L "${URL}" -o "${FILENAME}"
+}
+
 # Usage: downloadFromGithub USER REPO VERSION PACKAGE_PREFIX PACKAGE_SUFFIX TARGET
+#
 # Downloads a release package from github using the common architecture names
 # The package will be downloaded from github.com/USER/REPO/releases/VERSION/download/PACKAGE to the given TARGET file
 # where PACKAGE consists of PACKAGE_PREFIXARCHITECTURE.PACKAGE_SUFFIX.
@@ -77,4 +119,4 @@ function downloadFromGithub {
   ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/\(arm\)\(64\)\?.*/\1\2/' -e 's/aarch64$/arm64/')"
   PACKAGE="${PACKAGE_PREFIX}${ARCH}.${PACKAGE_SUFFIX}"
   execHandle "Downloading ${USER}/${REPO}@${VERSION}" curl -f -s -L "https://github.com/${USER}/${REPO}/releases/${VERSION}/download/${PACKAGE}" --output "${TARGET}"
-}
+}

feature/.template/feature.yaml

@@ -0,0 +1,18 @@
+# This is the metadata manifest for a feature. Configure it for the feature to be included in CloudControl
+# In your new feature, please remove all descriptive comments from the template.
+
+# Please use an emoji character as a meaningful logo for your feature
+icon: "⚙️"
+
+# Set the title for this feature
+title: "Direnv"
+
+# Set the description of the feature in Markdown. Be sure to include links to websites of the software the feature
+# installs or configures
+description: "Installs [Direnv](https://direnv.net/)"
+
+# Use the configuration key to list additional configuration options that you're providing in your feature
+configuration:
+    #- |
+    #    Environment EXAMPLE_ENVIRONMENT: This environment variable is used in the feature to do xyz (optional)
+    #    Defaults to `abc`

feature/.template/goss/.envrc

@@ -0,0 +1,2 @@
+# Setup required environment for test
+export EXAMPLE_ENVIRONMENT=something

feature/.template/goss/goss.yaml

@@ -0,0 +1,5 @@
+command:
+    test:
+        # Run ls / after installing the feature and if that returns successfully, the test is successful
+        exec: "ls /"
+        exit-status: 0

feature/.template/install.sh

@@ -0,0 +1,27 @@
+# The installer script for your feature, which is called in the init phase of CloudControl
+
+# Include the feature installer utils which include helpers for the installation of your feature
+# See /assets/feature-installer-utils.sh
+
+. /feature-installer-utils.sh
+
+# Create a temporary directory to work in
+prepare
+
+if [ "X${FLAVOUR}X" == "XsimpleX" ]
+then
+  # Do specific things for the simple flavour
+  download "https://example.com/my-tool-for-simple.tar.gz" tool.tar.gz
+elif [[ "X${FLAVOR}X" =~ X(azure|gcloud)X ]]
+then
+  # Do specific things for other flavours
+  download "https://example.com/my-tool-for-others.tar.gz" tool.tar.gz
+fi
+
+# Do other things
+execHandle "Extracting tool" tar xzf tool.tar.gz
+execHandle "Making tool executable" chmod +x tool
+execHandle "Copying tool to ${BINPATH}" cp tool "${BINPATH}"
+
+# Cleanup what we did
+cleanup