feat(docker): guide clone installation and validate paired update artifacts

scripts/docker-update.sh

@@ -3,6 +3,8 @@
 set -Eeuo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$DIR"
+source "$DIR/scripts/docker-update-options.sh"
+parse_update_options "$@" || exit 1
 exec 9>"$DIR/.deploy.lock"
 flock -w 1800 9
 LOG_FILE="${LOG_FILE:-$DIR/logs/docker-update.log}"
@@ -61,17 +63,20 @@ if [ "$(docker inspect --format '{{.State.Running}}' epicnext-cms-app 2>/dev/nul
   die "This host is managed by CI (epicnext-cms-app). Update through CI, not a second Compose deployment."
 fi
 [[ -z "$(git status --porcelain --untracked-files=normal)" ]] || die "Working tree is not clean. Commit or stash local work first."
-git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' >/dev/null || die "Configure this branch's Git upstream before updating."
-script_before="$(git hash-object scripts/docker-update.sh)"
-git pull --ff-only >>"$LOG_FILE" 2>&1
-if [ "$script_before" != "$(git hash-object scripts/docker-update.sh)" ]; then
-  log "Updater changed; restarting the newly pulled script."
-  exec 9>&-
-  exec bash "$DIR/scripts/docker-update.sh"
+if [[ "$UPDATE_SKIP_PULL" = 0 ]]; then
+  git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' >/dev/null || die "Configure this branch's Git upstream before updating."
+  script_before="$(git hash-object scripts/docker-update.sh)"
+  git pull --ff-only >>"$LOG_FILE" 2>&1
+  if [ "$script_before" != "$(git hash-object scripts/docker-update.sh)" ]; then
+    log "Updater changed; restarting the newly pulled script."
+    exec 9>&-
+    exec bash "$DIR/scripts/docker-update.sh" "$@"
+  fi
 fi
 # Load after pulling so image location changes follow the repository.
 source "$DIR/scripts/docker-config.sh"
 load_docker_config "$DIR" || die "Invalid .docker-install: expected MODE=prebuilt or source and PUBLIC_URL=http(s)://your-host."
+[[ -z "$UPDATE_APP_DIGEST" || -n "${CMS_IMAGE_REPOSITORY:-}" ]] || die "Digest selection requires prebuilt mode (registry access)."
 export CMS_RELEASE="$(git rev-parse HEAD)"
 [[ "$CMS_RELEASE" =~ ^[0-9a-f]{40}$ ]] || die "Invalid Git commit."
 [[ -f .env ]] || die "Create .env before installing or updating."
@@ -92,11 +97,14 @@ migration_image="epicnext-cms-migrations:$CMS_RELEASE"
 if [[ -n "${CMS_IMAGE_REPOSITORY:-}" ]]; then
   [[ "$CMS_IMAGE_REPOSITORY" =~ ^[a-z0-9.-]+(:[0-9]+)?/[a-z0-9._/-]+$ ]] || die "Invalid CMS_IMAGE_REPOSITORY; use registry/owner/image without a tag."
   log "Pulling prebuilt application and matching migrations for $CMS_RELEASE"
-  docker pull "$CMS_IMAGE_REPOSITORY:$CMS_RELEASE" >>"$LOG_FILE" 2>&1 || die "Application image unavailable. Publication for this commit may still be running; retry bash cms update after CI succeeds. For private packages, log in to the registry first."
+  app_reference="$CMS_IMAGE_REPOSITORY:$CMS_RELEASE"
+  [[ -z "$UPDATE_APP_DIGEST" ]] || app_reference="$CMS_IMAGE_REPOSITORY@$UPDATE_APP_DIGEST"
+  docker pull "$app_reference" >>"$LOG_FILE" 2>&1 || die "Application image unavailable. Publication for this commit may still be running; retry bash cms update after CI succeeds. For private packages, log in to the registry first."
   remote_migration_image="$CMS_IMAGE_REPOSITORY:$CMS_RELEASE-migrations"
+  [[ -z "$UPDATE_MIGRATIONS_DIGEST" ]] || remote_migration_image="$CMS_IMAGE_REPOSITORY@$UPDATE_MIGRATIONS_DIGEST"
   docker pull "$remote_migration_image" >>"$LOG_FILE" 2>&1 || die "Matching migrations image unavailable. Current CMS is unchanged; retry after publication succeeds."
-  docker tag "$CMS_IMAGE_REPOSITORY:$CMS_RELEASE" "epicnext-cms:$CMS_RELEASE"
-  docker tag "$CMS_IMAGE_REPOSITORY:$CMS_RELEASE-migrations" "$migration_image"
+  docker tag "$app_reference" "epicnext-cms:$CMS_RELEASE"
+  docker tag "$remote_migration_image" "$migration_image"
 else
   docker build --network=host --target migrations --build-arg NEXT_DEPLOYMENT_ID="$CMS_RELEASE" -t "$migration_image" . >>"$LOG_FILE" 2>&1
   docker compose build --build-arg NEXT_DEPLOYMENT_ID="$CMS_RELEASE" cms >>"$LOG_FILE" 2>&1
@@ -104,6 +112,11 @@ fi
 expected_image="$(docker image inspect --format '{{.Id}}' "epicnext-cms:$CMS_RELEASE")"
 revision="$(docker image inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' "$expected_image")"
 [[ "$revision" = "$CMS_RELEASE" ]] || die "Built image has revision $revision, expected $CMS_RELEASE."
+migration_revision="$(docker image inspect --format '{{index .Config.Labels "org.opencontainers.image.revision"}}' "$migration_image")"
+[[ "$migration_revision" = "$CMS_RELEASE" ]] || die "Migrations image has no matching release label. Rebuild/publish both artifacts from this checkout; the database was not changed."
+# Compose uses the candidate image's USER and exact mounts/env without starting the server.
+docker compose run --rm --no-deps --entrypoint node cms --input-type=module -e 'import {access,constants} from "node:fs/promises";import {validateRuntime} from "./docker-start.mjs";validateRuntime(process.env);for(const p of ["/app/storage","/app/public/nitro-assets","/app/public/swf","/var/www/Gamedata"]){try{await access(p,constants.R_OK|constants.W_OK|constants.X_OK)}catch{console.error("Runtime storage access denied: "+p);process.exit(1)}}' >>"$LOG_FILE" 2>&1 || die "Candidate configuration/storage validation failed; database unchanged. Check directory access for UID/GID 33."
+log "Before migration: ensure a verified database backup is available. Image rollback does not undo database migrations."
 migration_mounts=(--mount "type=bind,source=$DIR/.env,target=/app/.env,readonly")
 if [[ -f "$DIR/.env.local" ]]; then migration_mounts+=(--mount "type=bind,source=$DIR/.env.local,target=/app/.env.local,readonly"); fi
 docker run --rm --network host "${migration_mounts[@]}" --entrypoint pnpm "$migration_image" db:migrate >>"$LOG_FILE" 2>&1