Feature/wal wahl (#9)

* feat: wal-wahl installing multiple Docker versions side-by-side, switching between them. Signed-off-by: thediveo <thediveo@gmx.eu> * chore: feature description and version Signed-off-by: thediveo <thediveo@gmx.eu> * ci: fix: test all features Signed-off-by: thediveo <thediveo@gmx.eu> --------- Signed-off-by: thediveo <thediveo@gmx.eu>
thediveo · Jan 21, 2025 · 3deaec4 · 3deaec4
1 parent 9fd9871
commit 3deaec4
Show file tree

Hide file tree

Showing 12 changed files with 1,229 additions and 0 deletions.
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -15,6 +15,12 @@ jobs:
       matrix:
         features:
           - docsify
+          - go-mod-upgrade
+          - gocover
+          - goreportcard
+          - local-pkgsite
+          - pin-github-action
+          - wal-wahl
         baseImage:
           - mcr.microsoft.com/devcontainers/base:ubuntu-24.04
     steps:

diff --git a/generate-docs.sh b/generate-docs.sh
@@ -0,0 +1,6 @@
+#!/bin/bash
+devcontainer features generate-docs \
+    -n thediveo/devcontainer-features \
+    --github-owner thediveo \
+    --github-repo devcontainer-features \
+    -p ./src
diff --git a/src/wal-wahl/NOTES.md b/src/wal-wahl/NOTES.md
@@ -0,0 +1,88 @@
+## Trivia
+
+"Wal-Wahl" is a German pun with homophons, meaning picking/voting for a whale.
+
+## Usage
+
+Make sure to specify the Docker versions (separated by commas) you want to have
+installed into your devcontainer when requesting the `wal-wahl` feature:
+
+```json
+{
+  "features": {
+    "ghcr.io/thediveo/devcontainer-features/wal-wahl:0": {
+      "versions": "20,27"
+    }
+}
+}
+```
+
+Please note that the available Docker CE versions vary by distribution (Debian
+versus Ubuntu) and release (buster/bullseye/bookworm versus 20.04/22.04/24.04).
+
+This feature installs a command `/usr/local/bin/whale-select` to list the
+installed Docker versions, as well as to activate _one of them at a time_ or
+deactivate it without activating another one. It is _not possible_ to activate
+_multiple_ Docker versions _simultaneously_.
+
+### List Installed Versions
+
+`whale-select list` lists the Docker versions installed into this devcontainer.
+For instance:
+
+```
+$ whale-select list
+20.10.24
+26.1.4
+$ █
+```
+
+### Activating a Specific Version
+
+`whale-select VERSIONPREFIX` activates the Docker version starting with the
+specified VERSIONPREFIX; it will error if VERSIONPREFIX matches multiple
+installed Docker versions. If another Docker version is currently activated, it
+will be deactivated first.
+
+```
+$ sudo whale-select 26
+activating 26.1.4...
+$ █
+```
+
+```
+$ sudo whale-select 2
+error: ambiguous version "2" specified.
+available versions:
+    20.10.24
+    26.1.4
+$ █
+```
+
+### Deactivating
+
+`whale-select none` deselects the currently active Docker version (if any).
+It is no error when there is no currently activated Docker version.
+
+```
+$ sudo whale-select none
+deactivating current Docker/Moby...
+$ █
+```
+
+## Limitations
+
+- currently supports only installing Docker CE
+- no control over the compose plugin version (this is a limitation inherited
+  from Microsoft's DinD feature).
+
+## OS Support
+
+This Feature should work on recent versions of Debian/Ubuntu-based distributions
+with the `apt` package manager installed.
+
+`bash` is required to execute the `install.sh` and `dind/install.sh` scripts.
+
+## Superfluous Notes
+
+- best viewed on a VT100 terminal with amber CRT.
diff --git a/src/wal-wahl/README.md b/src/wal-wahl/README.md
@@ -0,0 +1,121 @@
+
+# install and switch between multiple Docker CE versions (wal-wahl)
+
+Install and switch between multiple Docker CE versions, activating one version at a time, and switching on-the-fly.
+
+## Example Usage
+
+```json
+"features": {
+    "ghcr.io/thediveo/devcontainer-features/wal-wahl:0": {}
+}
+```
+
+## Options
+
+| Options Id | Description | Type | Default Value |
+|-----|-----|-----|-----|
+| versions | list of Docker Engine versions, separated by comma | string | 26,27 |
+| azureDnsAutoDetection | Allow automatically setting the dockerd DNS server when the installation script detects it is running in Azure | boolean | false |
+| dockerDefaultAddressPool | Define default address pools for Docker networks. e.g. base=192.168.0.0/16,size=24 | string | - |
+| disableIp6tables | Disable ip6tables (this option is only applicable for Docker versions 27 and greater) | boolean | false |
+
+## Customizations
+
+### VS Code Extensions
+
+- `ms-azuretools.vscode-docker`
+
+## Trivia
+
+"Wal-Wahl" is a German pun with homophons, meaning picking/voting for a whale.
+
+## Usage
+
+Make sure to specify the Docker versions (separated by commas) you want to have
+installed into your devcontainer when requesting the `wal-wahl` feature:
+
+```json
+{
+  "features": {
+    "ghcr.io/thediveo/devcontainer-features/wal-wahl:0": {
+      "versions": "20,27"
+    }
+}
+}
+```
+
+Please note that the available Docker CE versions vary by distribution (Debian
+versus Ubuntu) and release (buster/bullseye/bookworm versus 20.04/22.04/24.04).
+
+This feature installs a command `/usr/local/bin/whale-select` to list the
+installed Docker versions, as well as to activate _one of them at a time_ or
+deactivate it without activating another one. It is _not possible_ to activate
+_multiple_ Docker versions _simultaneously_.
+
+### List Installed Versions
+
+`whale-select list` lists the Docker versions installed into this devcontainer.
+For instance:
+
+```
+$ whale-select list
+20.10.24
+26.1.4
+$ █
+```
+
+### Activating a Specific Version
+
+`whale-select VERSIONPREFIX` activates the Docker version starting with the
+specified VERSIONPREFIX; it will error if VERSIONPREFIX matches multiple
+installed Docker versions. If another Docker version is currently activated, it
+will be deactivated first.
+
+```
+$ sudo whale-select 26
+activating 26.1.4...
+$ █
+```
+
+```
+$ sudo whale-select 2
+error: ambiguous version "2" specified.
+available versions:
+    20.10.24
+    26.1.4
+$ █
+```
+
+### Deactivating
+
+`whale-select none` deselects the currently active Docker version (if any).
+It is no error when there is no currently activated Docker version.
+
+```
+$ sudo whale-select none
+deactivating current Docker/Moby...
+$ █
+```
+
+## Limitations
+
+- currently supports only installing Docker CE
+- no control over the compose plugin version (this is a limitation inherited
+  from Microsoft's DinD feature).
+
+## OS Support
+
+This Feature should work on recent versions of Debian/Ubuntu-based distributions
+with the `apt` package manager installed.
+
+`bash` is required to execute the `install.sh` and `dind/install.sh` scripts.
+
+## Superfluous Notes
+
+- best viewed on a VT100 terminal with amber CRT.
+
+
+---
+
+_Note: This file was auto-generated from the [devcontainer-feature.json](https://github.com/thediveo/devcontainer-features/blob/main/src/wal-wahl/devcontainer-feature.json).  Add additional notes to a `NOTES.md`._
diff --git a/src/wal-wahl/devcontainer-feature.json b/src/wal-wahl/devcontainer-feature.json
@@ -0,0 +1,50 @@
+{
+    "id": "wal-wahl",
+    "version": "0.1.0",
+    "name": "install and switch between multiple Docker CE versions",
+    "description": "Install and switch between multiple Docker CE versions, activating one version at a time, and switching on-the-fly.",
+    "options": {
+        "versions": {
+            "type": "string",
+            "default": "26,27",
+            "description": "list of Docker Engine versions, separated by comma"
+        },
+        "azureDnsAutoDetection": {
+            "type": "boolean",
+            "default": false,
+            "description": "Allow automatically setting the dockerd DNS server when the installation script detects it is running in Azure"
+        },
+        "dockerDefaultAddressPool": {
+            "type": "string",
+            "default": "",
+            "proposals": [],
+            "description": "Define default address pools for Docker networks. e.g. base=192.168.0.0/16,size=24"
+        },
+        "disableIp6tables": {
+            "type": "boolean",
+            "default": false,
+            "description": "Disable ip6tables (this option is only applicable for Docker versions 27 and greater)"
+        }
+   },
+   "privileged": true,
+   "containerEnv": {
+       "DOCKER_BUILDKIT": "1"
+   },
+   "customizations": {
+       "vscode": {
+           "extensions": [
+               "ms-azuretools.vscode-docker"
+           ]
+       }
+   },
+   "mounts": [
+       {
+           "source": "dind-var-lib-docker-${devcontainerId}",
+           "target": "/var/lib/docker",
+           "type": "volume"
+       }
+   ],
+   "installsAfter": [
+       "ghcr.io/devcontainers/features/common-utils"
+   ]
+}
diff --git a/src/wal-wahl/dind/LICENSE b/src/wal-wahl/dind/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/src/wal-wahl/dind/README.md b/src/wal-wahl/dind/README.md
@@ -0,0 +1,6 @@
+# README
+
+This installation script is taken from the "Docker-in-Docker" devcontainer
+feature, see
+https://github.com/devcontainers/features/tree/main/src/docker-in-docker. It is
+licensed by Microsoft under the MIT License, see [LICENSE](LICENSE).