Modernize Docker-Prep for VM-Setup pinned launches

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Resolve version
+        id: version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME}"
+          version_from_script=$(awk -F= '/^VERSION=/{ gsub(/"/, "", $2); print $2; exit }' install.sh)
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "script_version=$version_from_script" >> "$GITHUB_OUTPUT"
+          if [[ "$tag" != "v${version_from_script}" ]]; then
+            echo "Tag $tag does not match install.sh VERSION=$version_from_script" >&2
+            exit 1
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          notes_file=$(mktemp)
+          cat > "$notes_file" <<EOF
+          ## Docker-Prep ${TAG}
+
+          Pinned consumer note: VM-Setup syncs this release through its
+          Sync Docker-Prep pin workflow.
+
+          Entrypoint: bash install.sh
+          Ephemeral launch env:
+          - DOCKER_PREP_EPHEMERAL=1
+          - DOCKER_PREP_REVISION=<commit sha>
+          EOF
+          gh release create "$TAG" \
+            --title "Docker-Prep ${TAG}" \
+            --notes-file "$notes_file"
+
+      - name: Notify VM-Setup pin sync
+        env:
+          GH_TOKEN: ${{ secrets.VM_SETUP_DISPATCH_TOKEN }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${GH_TOKEN:-}" ]]; then
+            echo "VM_SETUP_DISPATCH_TOKEN not configured; skipping repository_dispatch."
+            exit 0
+          fi
+          gh api \
+            --method POST \
+            -H "Accept: application/vnd.github+json" \
+            "/repos/Narehood/VM-Setup/dispatches" \
+            -f event_type='docker-prep-release' \
+            -f "client_payload[tag]=${TAG}"

.github/workflows/shell-security.yml

@@ -0,0 +1,30 @@
+name: Shell security checks
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install analysis tools
+        run: sudo apt-get update && sudo apt-get install -y shellcheck ripgrep
+
+      - name: Validate syntax and security policy
+        run: bash tests/security-checks.sh
+
+      - name: Run ShellCheck
+        run: |
+          shellcheck --severity=error \
+            install.sh \
+            Scripts/*.sh \
+            tests/*.sh \
+            tools/*.sh

.gitignore

@@ -0,0 +1,4 @@
+.docker-prep-pin-update.md
+*.swp
+*~
+.DS_Store

README.md

@@ -19,7 +19,7 @@
 Detects your OS, installs the official Docker Engine, creates dedicated users with correct permissions,<br>
 and optionally deploys Portainer for immediate container management.
 
-[Features](#-features) • [Quick Start](#-quick-start) • [Capabilities](#-capabilities) • [Notes](#%EF%B8%8F-important-notes)
+[Features](#-features) • [Quick Start](#-quick-start) • [Capabilities](#-capabilities) • [VM-Setup](#-vm-setup-integration) • [Notes](#%EF%B8%8F-important-notes)
 
 </div>
 
@@ -57,6 +57,7 @@ bash install.sh
 | **User Management** | Creates a dedicated Docker user or configures existing users for rootless access |
 | **Permission Fix** | Automatically handles group assignments (`usermod -aG docker`) |
 | **Portainer Ready** | Option to instantly deploy [Portainer](https://www.portainer.io/) via the script |
+| **Checksum Gate** | Verifies `Scripts/*.sh` against `Scripts/.checksums.sha256` before execution |
 | **Secure Defaults** | Ensures proper service enabling and user permission handling |
 
 ---
@@ -67,10 +68,53 @@ The script guides you through a simplified menu to perform the following:
 
 | Action | Description |
 | :--- | :--- |
-| **Install Docker Engine** | Updates repositories, installs dependencies, and sets up the Docker daemon |
+| **Install Docker Engine** | Downloads the official installer to a temp file, then runs it (never `curl \| sh`) |
 | **User Configuration** | Creates a new user specifically for Docker or adds your current user |
 | **Security Groups** | Adds the selected user to the `docker` group for non-root command execution |
-| **Portainer Deployment** | Pulls and runs the Portainer CE container on port 9443 |
+| **Portainer Deployment** | Pulls and runs Portainer CE pinned to the `lts` image tag on port 9443 |
+
+---
+
+## 🔗 VM-Setup Integration
+
+[VM-Setup](https://github.com/Narehood/VM-Setup) launches Docker-Prep from a pinned revision in a temporary checkout.
+
+| Variable | Purpose |
+| :--- | :--- |
+| `DOCKER_PREP_EPHEMERAL=1` | Marks the launch as temporary; disables self-update |
+| `DOCKER_PREP_REVISION=<sha>` | Displays the pinned commit in the UI |
+
+Example:
+
+```bash
+DOCKER_PREP_EPHEMERAL=1 DOCKER_PREP_REVISION=<full-sha> bash ./install.sh
+```
+
+VM-Setup syncs its pin when this repository publishes a GitHub Release.
+
+### Publishing a release
+
+1. Bump `VERSION` in `install.sh` (for example `2.4.0`).
+2. Commit the change.
+3. Tag and push: `git tag v2.4.0 && git push origin v2.4.0`
+4. The Release workflow creates the GitHub Release and, when `VM_SETUP_DISPATCH_TOKEN` is configured, notifies VM-Setup via `repository_dispatch` (`docker-prep-release`).
+
+---
+
+## 🔒 Integrity tooling
+
+Regenerate the trusted checksum manifest after changing any file under `Scripts/`:
+
+```bash
+bash tools/generate-checksums.sh
+```
+
+Local validation (matches CI):
+
+```bash
+bash tests/security-checks.sh
+shellcheck --severity=error install.sh Scripts/*.sh tests/*.sh tools/*.sh
+```
 
 ---
 
@@ -81,6 +125,7 @@ The script guides you through a simplified menu to perform the following:
 | **Root Access** | Script must be run as root or with `sudo` privileges |
 | **Re-Login Required** | Log out and back in after adding a user to the Docker group |
 | **Portainer** | If installed, accessible at `https://<your-ip>:9443` |
+| **Ephemeral launches** | When launched from VM-Setup, update the pin there instead of using menu self-update |
 
 ---
 

Scripts/.checksums.sha256

@@ -0,0 +1,4 @@
+7765e55bf2bd3e269ac078f7e1a10c013a0c04a6c53282f372746342cd326181  DockerGroup.sh
+ff5479ac784e1e93c4fb7094cbba4d75e2188fb7fd10294166f26376052caa68  portainer-install.sh
+bd647935533e2354db2ba0c2386ba3ea6c6222feed629c55048bcc0eae872f8a  serverSetup.sh
+dece1be99a98476bbcebdc745123a265b7bf313c8bf3191fb5ac98c2011fb52b  UserCreation.sh

Scripts/DockerGroup.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -euo pipefail
 
 # Docker Group Management Script
 # Adds a user to the docker group for rootless container management
@@ -7,6 +8,7 @@
 
 # DIRECTORY ANCHOR
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC2034
 SCRIPT_PATH="$SCRIPT_DIR/$(basename -- "${BASH_SOURCE[0]}")"
 
 # VISUAL STYLING
@@ -49,6 +51,7 @@ fi
 detect_os() {
     OS="unknown"
     if [[ -f /etc/os-release ]]; then
+        # shellcheck disable=SC1091
         source /etc/os-release
         OS="$ID"
     elif [[ -f /etc/redhat-release ]]; then

Scripts/UserCreation.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+set -euo pipefail
 
 # User Creation Script
 # Creates a new user with optional docker group membership
@@ -7,6 +8,8 @@
 
 # DIRECTORY ANCHOR
 SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
+# shellcheck disable=SC2034
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
 
 # VISUAL STYLING
 RED='\033[0;31m'
@@ -48,6 +51,7 @@ fi
 detect_os() {
     OS="unknown"
     if [[ -f /etc/os-release ]]; then
+        # shellcheck disable=SC1091
         source /etc/os-release
         OS="${ID,,}"
     elif [[ -f /etc/redhat-release ]]; then

Scripts/portainer-install.sh

@@ -1,12 +1,16 @@
 #!/bin/bash
+set -euo pipefail
 
 # Portainer CE Installation Script
 # Deploys Portainer using the official LTS compose file
-# Version: 1.1.0
+# Version: 1.2.0
+# DESCRIPTION: Install Portainer CE using the official LTS compose file
 
 # DIRECTORY ANCHOR
 SCRIPT_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
 SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+readonly PORTAINER_IMAGE="portainer/portainer-ce:lts"
+SUDO=""
 
 # VISUAL STYLING
 RED='\033[0;31m'
@@ -155,31 +159,51 @@ check_existing_portainer() {
     return 0
 }
 
+# pin_portainer_image rewrites floating Portainer image tags to the pinned LTS tag.
+pin_portainer_image() {
+    local compose_file="$1"
+
+    print_info "Pinning Portainer image to ${PORTAINER_IMAGE}..."
+    if ! $SUDO grep -qE 'image:[[:space:]]*"?portainer/portainer-ce' "$compose_file"; then
+        print_error "Compose file does not reference official Portainer CE image."
+        return 1
+    fi
+
+    $SUDO sed -i -E 's|(image:[[:space:]]*"?)portainer/portainer-ce(:[A-Za-z0-9._-]+)?("?)|\1'"${PORTAINER_IMAGE}"'\3|' "$compose_file"
+    if ! $SUDO grep -qE 'image:[[:space:]]*"?portainer/portainer-ce:lts"?$' "$compose_file"; then
+        print_error "Failed to pin Portainer image tag."
+        return 1
+    fi
+
+    print_success "Portainer image pinned."
+    return 0
+}
+
 # validate_compose_file validates a Docker Compose file for Portainer by checking that the file exists and is non-empty, contains a Portainer service and the official `portainer/portainer-ce` image reference, and has valid YAML syntax according to `docker compose config`; returns 0 on success and 1 on failure.
 validate_compose_file() {
     local compose_file="$1"
 
     print_info "Validating compose file..."
 
-    if [ ! -f "$compose_file" ]; then
+    if [[ ! -f "$compose_file" ]]; then
         print_error "Compose file not found."
         return 1
     fi
 
-    if [ ! -s "$compose_file" ]; then
+    if [[ ! -s "$compose_file" ]]; then
         print_error "Compose file is empty."
         return 1
     fi
 
     # Check for expected Portainer service definition
-    if ! grep -q "portainer" "$compose_file"; then
+    if ! $SUDO grep -q "portainer" "$compose_file"; then
         print_error "Compose file does not contain expected Portainer service."
         return 1
     fi
 
-    # Check for portainer image reference
-    if ! grep -qE "portainer/portainer-ce" "$compose_file"; then
-        print_error "Compose file does not reference official Portainer CE image."
+    # Check for pinned portainer image reference
+    if ! $SUDO grep -qE "image:[[:space:]]*\"?portainer/portainer-ce:lts\"?" "$compose_file"; then
+        print_error "Compose file does not reference pinned Portainer CE LTS image."
         return 1
     fi
 
@@ -202,8 +226,8 @@ deploy_portainer() {
     echo ""
     print_info "Deploying Portainer CE (LTS)..."
 
-    if [ ! -w "/opt" ]; then
-        if [ "$EUID" -ne 0 ]; then
+    if [[ ! -w "/opt" ]]; then
+        if [[ "$EUID" -ne 0 ]]; then
             print_warn "Root privileges required to create $compose_dir"
             read -rp "  Use sudo for directory creation? (Y/n): " use_sudo
             use_sudo="${use_sudo:-y}"
@@ -220,8 +244,7 @@ deploy_portainer() {
     fi
 
     print_info "Creating directory: $compose_dir"
-    $SUDO mkdir -p "$compose_dir"
-    if [ $? -ne 0 ]; then
+    if ! $SUDO mkdir -p "$compose_dir"; then
         print_error "Failed to create directory."
         return 1
     fi
@@ -236,6 +259,11 @@ deploy_portainer() {
         return 1
     fi
 
+    if ! pin_portainer_image "$compose_file"; then
+        $SUDO rm -f "$compose_file"
+        return 1
+    fi
+
     # Validate the downloaded file
     if ! validate_compose_file "$compose_file"; then
         print_error "Downloaded compose file failed validation."
@@ -247,16 +275,13 @@ deploy_portainer() {
     print_info "Starting Portainer containers..."
     echo ""
 
-    cd "$compose_dir" || return 1
-
-    if $SUDO docker compose -f "$compose_file" up -d; then
-        echo ""
-        print_success "Portainer deployed successfully!"
-    else
+    if ! $SUDO docker compose -f "$compose_file" up -d; then
         print_error "Failed to deploy Portainer."
         return 1
     fi
 
+    echo ""
+    print_success "Portainer deployed successfully!"
     return 0
 }