ERA-1706 Add safe Docker app rebuild workflow

.github/workflows/Docker.yml

@@ -6,8 +6,39 @@ on:
       - '*'
 
 jobs:
+  shell_tests:
+    name: Rebuild App Shell Tests
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+
+      - name: Run rebuild-app tests
+        run: >-
+          npx --yes bats@1.12.0
+          tests/rebuild-app-test-helper.bats
+          tests/rebuild-app-options.bats
+          tests/rebuild-app-plan.bats
+          tests/rebuild-app-lifecycle.bats
+
+      - name: Check Bash syntax
+        run: bash -n rebuild-app lib/rebuild-app/common.sh lib/rebuild-app/plan.sh lib/rebuild-app/docker.sh
+
+      - name: Check immutable image interpolation
+        run: |
+          community_images=$(ERAMBA_IMAGE_TAG=3.30.1-6 docker compose \
+            -f docker-compose.simple-install.yml config --images)
+          enterprise_images=$(ERAMBA_IMAGE_TAG=3.30.1-6 docker compose \
+            -f docker-compose.simple-install.yml \
+            -f docker-compose.simple-install.enterprise.yml config --images)
+
+          test "$(grep -c '^ghcr.io/eramba/eramba:3.30.1-6$' <<<"$community_images")" -eq 2
+          test "$(grep -c '^ghcr.io/eramba/eramba-enterprise:3.30.1-6$' <<<"$enterprise_images")" -eq 2
+
   simple_install:
     name: Simple Installation [${{ matrix.build-type }}]
+    needs: shell_tests
     runs-on: ubuntu-22.04
     strategy:
       fail-fast: false

.gitignore

@@ -33,3 +33,4 @@ nbproject/*
 .vscode
 # Sass preprocessor
 .sass-cache/
+.rebuild-app/

README.md

@@ -1,3 +1,42 @@
 Welcome to eramba's official Github account, for Docker installs please review our website Learning Platform ([eramba.org](https://www.eramba.org/learning/courses/12/episodes/274)) under Docker Install.
 
 The bundled files in `apache/ssl/` are a branded local development certificate intended only for local or simple demo installs. It is signed by a local development CA and will only be trusted on machines where that CA has been installed. Replace it with your own CA-issued certificate and private key for any real deployment.
+
+## Rebuild the application image
+
+`./rebuild-app` replaces the application image and `/var/www/eramba` code volume using the canonical image-switch plan returned by the running Eramba application. The running image must include `bin/cake image_switch_plan`. Installations older than that baseline must follow the documented manual image-switch procedure once before using this command; there is no target-tag override.
+
+Review the complete plan without changing `.env`, containers, or volumes:
+
+```bash
+./rebuild-app --dry-run
+```
+
+Run an interactive Community rebuild:
+
+```bash
+./rebuild-app
+```
+
+Enterprise archives must be downloaded manually before the rebuild:
+
+```bash
+./rebuild-app --edition enterprise \
+  --image-file eramba-enterprise-<tag>-amd64.tar
+```
+
+Update a clean, attached Docker checkout with `git pull --ff-only` before preflight:
+
+```bash
+./rebuild-app --update-repo
+```
+
+For non-interactive execution, both the plan and a current recoverable backup must be confirmed explicitly:
+
+```bash
+./rebuild-app --yes --backup-confirmed
+```
+
+The command pulls the exact Community image or validates the exact image loaded from an Enterprise archive before downtime. During a normal rebuild, MySQL and Redis stay running. Only the twice-verified volume mounted at `/var/www/eramba` is removed; database, application data, logs, and trigger-storage volumes are preserved. Eramba completes its migration-aware startup and health checks before cron and triggers are started.
+
+Failures before the first target `eramba` start restore the previous image tag and application services automatically. After that migration boundary, the command does not downgrade application code because database migrations may already have run. It keeps unverified dependent services stopped and writes private diagnostics under `.rebuild-app/runs/`; review those diagnostics and the database restore requirements before attempting recovery.

docker-compose.simple-install.enterprise.yml

@@ -1,5 +1,5 @@
 services:
   eramba:
-    image: ghcr.io/eramba/eramba-enterprise:latest
+    image: ghcr.io/eramba/eramba-enterprise:${ERAMBA_IMAGE_TAG:-latest}
   cron:
-    image: ghcr.io/eramba/eramba-enterprise:latest
+    image: ghcr.io/eramba/eramba-enterprise:${ERAMBA_IMAGE_TAG:-latest}

docker-compose.simple-install.yml

@@ -24,7 +24,7 @@ services:
       - app_internal
   eramba:
     container_name: eramba
-    image: ghcr.io/eramba/eramba:latest
+    image: ghcr.io/eramba/eramba:${ERAMBA_IMAGE_TAG:-latest}
     restart: always
     ports:
       - 8443:443
@@ -65,7 +65,7 @@ services:
       - triggers_net
   cron:
     container_name: cron
-    image: ghcr.io/eramba/eramba:latest
+    image: ghcr.io/eramba/eramba:${ERAMBA_IMAGE_TAG:-latest}
     command: ["cron", "-f"]
     entrypoint: ["/docker-cron-entrypoint.sh"]
     restart: always