feat(build-tests): Phase 2 — live end-to-end integration tests (#146)

[bradymiller]

Summary

Phase 2 of #146 — live end-to-end integration tests for demo_build.sh.

Builds on #147 (Phase 1's dry-run suite, merged as 91477d1). The diff here is rebased onto master and shows only the Phase 2 changes.

tools/build-tests/integration/run-scenario.sh stands up mariadb:10.6 + an openemr/openemr:flex-3.22-php-8.2 container on an isolated docker network, runs demo_build.sh for real (composer install, npm install, webpack themes build, OpenEMR install, mariadb populate, apache start), then asserts:

1. The script reaches its "Demo install script is complete" marker within a 20-min timeout (i.e., walked the full happy path including the slow phases that dry-run skips).
2. Every expected database exists in mariadb and has a globals table (sanity check that InstallerAuto.php actually ran).
3. The captured action log matches a per-fixture expected/live-action-log.txt golden (after normalizing the per-run-varying mariadb container hostname and the randomly-picked theme value).

Same fixtures Phase 1 uses; no fixture duplication. Container + network are cleaned up on EXIT (success or failure).

Scenarios run live

Three of Phase 1's seven, picked to exercise distinct expensive behavior:

Fixture	What this catches in live mode that dry-run can't
branch-pinned-master	master clone + real composer dep resolution + webpack themes build + ppapi globals UPDATE + dev-translations install path
tag-pinned-with-data	tag clone + demo data SQL load + demoDataUpgrade (sed transforms + ALTER TABLE/DATABASE on $v_major≥6)
release-packageserve	the entire packageServe block — a second composer/npm/phing pass in a staging dir + tar/zip/md5sum packaging output

The 4 remaining stay dry-run-only — light-reset/multi-demo are too expensive per signal added (lightReset just gates the post-loop block; multi-demo costs 3× composer for what action-log diff already proves); capsule-path-traversal exits before any side effect; up-for-grabs-fork depends on a community fork's branch state (flaky-by-design).

CI: matrix-parallel + scheduled

.github/workflows/build-tests-live.yml runs each scenario on its own ubuntu-24.04 runner via strategy.matrix. Wall time = slowest cell (~10 min) instead of sum (~25 min sequential). fail-fast: false so a single cell failing doesn't cancel its siblings — debugging needs to see all three results.

Actual matrix timings observed on this PR:

Cell	Wall time
live (branch-pinned-master)	3m30s
live (tag-pinned-with-data)	8m21s
live (release-packageserve)	9m53s
Workflow wall time	9m53s (vs 24m43s sequential — ~60% reduction)

Three triggers, complementary:

• pull_request — per-push feedback on PRs that touch demo_build.sh / tools/build-tests/**. Made viable by the matrix cutting wall time to ~10 min.
• schedule: '0 8 * * *' — daily 08:00 UTC, 1h after the auto-derive reconcile. Catches the class no PR triggers: upstream image bumps (Alpine, mariadb 10.6 → 10.7, openemr/flex) that break demo_build.sh assumptions without anyone editing it.
• workflow_dispatch — manual reruns for debugging a flaky scheduled run.

What this PR deliberately does NOT do

• Direct diff against Phase 1 dry-run goldens. Each fixture gets its own expected/live-action-log.txt instead. A direct diff would need Phase 1 goldens redesigned with abstract path tokens (<OPENEMR> instead of <WORK>/web/openemr) — non-trivial scope creep. The two-golden split lets human reviewers diff both files manually if they want the "dry-run vs live drift" signal. (Real example surfaced during smoke testing: dry-run logs rm -f ofc_upload_image.php because the fixture pre-creates the marker file; live doesn't, because upstream openemr already removed that file. Both behaviors are correct — the script handles both presence and absence — but the goldens differ on that line.)
• Composer/npm caching. First iteration accepts cold runs. actions/cache for ~/.composer/cache + ~/.npm is a small follow-up that would bring per-cell time down further.
• Artifact upload on failure. run-scenario.sh already prints container logs + setup-log tail on every failure path; visible in the workflow log.
• GitHub auth for composer. No github-key is mounted in CI, so the script's cat /home/openemr/github-key fails (silently, no set -e), the rate-limit curl returns 60-remaining from an unauthenticated call, and the script takes the "not using composer github api token" branch. Works for one nightly run; risk if rate-limited.

Rabbit-flagged items addressed mid-review

• 1a21699 — --image CLI flag now takes precedence over fixture's INTEGRATION_IMAGE (lets callers A/B-test a scenario against a different image without editing the fixture).
• 625cda9 — drop dead PHP_VERSION_ABBR sourcing in run-scenario.sh (the flex image provides its own; runner-side source was a contract this script doesn't actually have).
• fa9e75b — matrix conversion (this).
• 9de9553 — schedule trigger added; pre-merge pull_request-drop TODO retired.

Test plan

• ./tools/build-tests/integration/run-scenario.sh branch-pinned-master — local smoke (PASS)
• ./tools/build-tests/integration/run-all.sh locally — all 3 scenarios (PASS)
• CI matrix on this PR — all 3 cells green at 9m53s slowest
• Manual review of each live golden (expected/live-action-log.txt) — production paths, normalized hostnames + theme + redacted secrets, expected branching covered
• CodeRabbit: review completed (2 actionable rounds addressed; remaining nitpicks documented in comment thread with rationale)

Refs: #146 (issue), #147 (Phase 1)

🤖 Generated with Claude Code

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds dry-run logging and fixture-based validation for demo_build.sh, plus Docker-backed live scenario execution and new workflow entrypoints for both paths.

Changes

Build-test harness: dry-run + Phase 1/2 integration

Layer / File(s)	Summary
CI workflows and runner entrypoints .github/workflows/build-tests.yml, .github/workflows/build-tests-live.yml, .shellcheckrc, tools/build-tests/integration/run-all.sh	Adds the dry-run and live workflow triggers, job permissions, checkout and execution steps, ShellCheck suppressions, and the sequential live-scenario runner.
demo_build.sh dry-run framework demo_build.sh	Adds dry-run parsing, action-log helpers, captured-output stubbing, fixture-friendly path overrides, and dry-run theme placeholders.
demo_build.sh operational steps wrapped demo_build.sh	Routes clone, copy, install, installer, data upgrade, capsule restore, SQL updates, packaging, and service startup steps through the new action helpers.
Phase 1 dry-run test harness tools/build-tests/test.sh	Creates isolated fixture work trees, overlays fixture content, runs demo_build.sh in dry-run mode, normalizes action logs, checks golden and fail-expected outputs, and prints the fixture summary.
Phase 2 live integration runner tools/build-tests/integration/run-scenario.sh	Parses scenario options, creates Docker resources, stages fixture bind mounts, starts MariaDB and OpenEMR containers, validates database state, and diffs normalized live action logs.
Scenario fixtures and expected logs tools/build-tests/fixtures/*	Adds branch-pinned, capsule traversal, light-reset, multi-demo, release-packageserve, tag-pinned-with-data, and up-for-grabs-fork fixtures with inputs, IP maps, and expected action logs.

Sequence Diagram(s)

sequenceDiagram
  participant GitHubActions
  participant test.sh
  participant run-all.sh
  participant run-scenario.sh
  participant demo_build.sh
  GitHubActions->>test.sh: run dry-run fixtures
  GitHubActions->>run-scenario.sh: run live scenario
  run-all.sh->>run-scenario.sh: invoke each live scenario
  test.sh->>demo_build.sh: run --dry-run
  run-scenario.sh->>demo_build.sh: use fixture action log

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• Proposal: migrate openemr docker images and pipelines to openemr core, one Dockerfile per rel branch openemr-devops#790: The new workflows and Docker-based integration flow align with the build-test pipeline work in that issue.
• Add regression testing for demo_build.sh + orchestration scripts #146: This PR implements the dry-run fixture harness and live integration runner described by that issue.

Possibly related PRs

• openemr/demo_farm_openemr#135: Both PRs modify demo_build.sh and its branch/tag execution flow, so they touch the same build path.
• openemr/demo_farm_openemr#146: This PR directly implements the dry-run/live regression-test flow referenced by the same build-test orchestration.

Poem

🐇 I hop through logs and golden light,
With Docker moons and fixtures bright.
--dry-run hums, the tests align,
Then live runs sing: all green, just fine.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 69.23% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: Phase 2 live end-to-end build-tests integration for issue #146.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (4)

tools/build-tests/integration/run-scenario.sh (1)

39-40: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Pin the container images by digest.

These live goldens are supposed to catch demo_build.sh regressions, but mutable tags can make the suite fail when upstream republishes either image. Prefer image@sha256:... here and keep tag changes explicit.

Also applies to: 164-170

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tools/build-tests/integration/run-scenario.sh` around lines 39 - 40, The
container images used in run-scenario.sh are currently pinned only by mutable
tags, which can make the golden tests flaky when upstream republishes images.
Update the IMAGE assignment and the other image references in the same script to
use digest-pinned image@sha256 identifiers instead of tags, and keep any future
tag changes explicit by changing the digest reference in one place.

.github/workflows/build-tests-live.yml (1)

22-29: 🚀 Performance & Scalability | 🔵 Trivial

Resolve the pre-merge trigger TODO before landing.

This still ships pull_request and omits the nightly schedule, so the repo keeps the 20–45 minute PR cost and never gets the intended post-merge coverage described in the header and PR objective.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/build-tests-live.yml around lines 22 - 29, Update the
workflow trigger configuration in the build-tests-live workflow so it no longer
runs on pull_request and instead includes the intended nightly schedule trigger.
Keep the existing path filters for the relevant build/test files, and make sure
the workflow’s trigger block matches the post-merge coverage goal described by
the workflow header and objective.

.shellcheckrc (1)

36-37: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Scope these ShellCheck disables to demo_build.sh

These are repo-wide suppressions for bashisms that all come from demo_build.sh’s stale #!/bin/sh shebang. Switch that script to bash, or scope the suppressions there, so the rest of the repo keeps ShellCheck coverage.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.shellcheckrc around lines 36 - 37, The ShellCheck suppressions for SC3043
and SC3050 are currently applied repo-wide in .shellcheckrc, but they only
relate to bashisms used by demo_build.sh. Move or scope these disables to
demo_build.sh, or update demo_build.sh to use bash so the rest of the repo keeps
ShellCheck coverage; use the demo_build.sh script and the .shellcheckrc entries
as the places to adjust.

demo_build.sh (1)

821-824: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider mkdir -p for $FILESSERVEDIR to match Line 773 and stay idempotent.

Line 773 uses mkdir -p (unwrapped, by design), but Line 824 uses bare mkdir, which errors if $FILESSERVEDIR already exists or its parent is missing—e.g. on a re-invocation in a running container. -p keeps the unwrapped-for-dry-run intent while remaining idempotent.

♻️ Suggested change

-  mkdir $FILESSERVEDIR
+  mkdir -p $FILESSERVEDIR

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@demo_build.sh` around lines 821 - 824, The `$FILESSERVEDIR` setup in the web
file directory creation step should be idempotent like the earlier directory
creation logic. Update the `mkdir` call used before the `cd $FILESSERVEDIR` flow
to use the same `-p` behavior as the other directory setup, so reruns do not
fail if the directory already exists or the parent path is missing.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@demo_build.sh`:
- Around line 56-72: Extend the redaction in _emit_action_log so it also strips
Composer GitHub credentials from live-run output, not just mariadb passwords and
rootpass values. Update the sed-based filtering to catch Authorization headers
and the github-oauth.github.com token form emitted by the curl and composer
config paths, so ACTION_LOG cannot capture $GITHUB_KEY_COMPOSER or similar
secrets during Phase 2 runs.

In `@tools/build-tests/integration/run-scenario.sh`:
- Around line 43-46: The CLI parsing in run-scenario.sh currently lets the
fixture source overwrite the --image value, so --image is not the
highest-precedence override. Update the image assignment flow so the
fixture-provided value is only used as a default when IMAGE was not already set
by the argument parser in the while/case block, preserving the user-supplied
--image for all scenarios including those with INTEGRATION_IMAGE.

In `@tools/build-tests/test.sh`:
- Around line 18-24: Update the fixture path example in the `test.sh` comments
so it matches how `cp -a "$extra_dir/." "$work/"` applies overrides. The
`extra/openemr/version.php` example should include the `web/` prefix to reflect
the actual `"$WEB/openemr/version.php"` location, and the surrounding guidance
for `extra/` marker contents should be adjusted consistently.

---

Nitpick comments:
In @.github/workflows/build-tests-live.yml:
- Around line 22-29: Update the workflow trigger configuration in the
build-tests-live workflow so it no longer runs on pull_request and instead
includes the intended nightly schedule trigger. Keep the existing path filters
for the relevant build/test files, and make sure the workflow’s trigger block
matches the post-merge coverage goal described by the workflow header and
objective.

In @.shellcheckrc:
- Around line 36-37: The ShellCheck suppressions for SC3043 and SC3050 are
currently applied repo-wide in .shellcheckrc, but they only relate to bashisms
used by demo_build.sh. Move or scope these disables to demo_build.sh, or update
demo_build.sh to use bash so the rest of the repo keeps ShellCheck coverage; use
the demo_build.sh script and the .shellcheckrc entries as the places to adjust.

In `@demo_build.sh`:
- Around line 821-824: The `$FILESSERVEDIR` setup in the web file directory
creation step should be idempotent like the earlier directory creation logic.
Update the `mkdir` call used before the `cd $FILESSERVEDIR` flow to use the same
`-p` behavior as the other directory setup, so reruns do not fail if the
directory already exists or the parent path is missing.

In `@tools/build-tests/integration/run-scenario.sh`:
- Around line 39-40: The container images used in run-scenario.sh are currently
pinned only by mutable tags, which can make the golden tests flaky when upstream
republishes images. Update the IMAGE assignment and the other image references
in the same script to use digest-pinned image@sha256 identifiers instead of
tags, and keep any future tag changes explicit by changing the digest reference
in one place.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 81014f65-e2f8-4749-a6f6-cf8b4e919b7b

📥 Commits

Reviewing files that changed from the base of the PR and between 000d131 and 098ae80.

📒 Files selected for processing (33)

• .github/workflows/build-tests-live.yml
• .github/workflows/build-tests.yml
• .shellcheckrc
• demo_build.sh
• tools/build-tests/fixtures/branch-pinned-master/expected/action-log.txt
• tools/build-tests/fixtures/branch-pinned-master/expected/live-action-log.txt
• tools/build-tests/fixtures/branch-pinned-master/inputs.env
• tools/build-tests/fixtures/branch-pinned-master/ip_map_branch.txt
• tools/build-tests/fixtures/capsule-path-traversal/expected/fail.txt
• tools/build-tests/fixtures/capsule-path-traversal/inputs.env
• tools/build-tests/fixtures/capsule-path-traversal/ip_map_branch.txt
• tools/build-tests/fixtures/light-reset/expected/action-log.txt
• tools/build-tests/fixtures/light-reset/inputs.env
• tools/build-tests/fixtures/light-reset/ip_map_branch.txt
• tools/build-tests/fixtures/multi-demo/expected/action-log.txt
• tools/build-tests/fixtures/multi-demo/inputs.env
• tools/build-tests/fixtures/multi-demo/ip_map_branch.txt
• tools/build-tests/fixtures/release-packageserve/expected/action-log.txt
• tools/build-tests/fixtures/release-packageserve/expected/live-action-log.txt
• tools/build-tests/fixtures/release-packageserve/inputs.env
• tools/build-tests/fixtures/release-packageserve/ip_map_branch.txt
• tools/build-tests/fixtures/tag-pinned-with-data/expected/action-log.txt
• tools/build-tests/fixtures/tag-pinned-with-data/expected/live-action-log.txt
• tools/build-tests/fixtures/tag-pinned-with-data/extra/git/demo_farm_openemr/pieces/demo_5_0_0_5.sql
• tools/build-tests/fixtures/tag-pinned-with-data/inputs.env
• tools/build-tests/fixtures/tag-pinned-with-data/ip_map_branch.txt
• tools/build-tests/fixtures/up-for-grabs-fork/expected/action-log.txt
• tools/build-tests/fixtures/up-for-grabs-fork/extra/git/demo_farm_openemr/pieces/demo_5_0_0_5.sql
• tools/build-tests/fixtures/up-for-grabs-fork/inputs.env
• tools/build-tests/fixtures/up-for-grabs-fork/ip_map_branch.txt
• tools/build-tests/integration/run-all.sh
• tools/build-tests/integration/run-scenario.sh
• tools/build-tests/test.sh

[bradymiller]

Thanks for the review. Quick notes on the three nitpicks I'm not addressing in this PR — each has a "fix not in this PR's scope" rationale:

Pin images by digest (run-scenario.sh L39-40 / L164-170): the whole point of the nightly live job is to surface upstream image regressions (an Alpine base bump, a mariadb major change, etc.). Digest-pinning would mean the nightly only ever tests what we pinned, missing the exact class of bug Phase 2 is supposed to catch. Production demo_build.sh runs against the same mutable tags (openemr/openemr:flex-3.22-php-8.2, mariadb:10.6) — testing against them keeps signal aligned with reality. If a tag republish breaks the suite, that's the suite working as designed.

Switch trigger from pull_request to schedule (build-tests-live.yml L22-29): explicitly deferred to a pre-merge commit on this same branch — the workflow's own header comment block (lines 22-29) documents this. Switching now would lose the per-push CI feedback we're actively using to iterate on this PR. The final pre-merge commit will swap pull_request for schedule: cron '0 8 * * *'.

Scope SC3043/SC3050 disables to demo_build.sh (.shellcheckrc L36-37): the 5 pre-existing SC3xxx disables in this file are all for the same root cause (demo_build.sh's stale #!/bin/sh shebang with bash bodies). Scoping just SC3043/SC3050 would make the rc inconsistent — either all five get inline-scoped or none. That's a separate ratchet cleanup (along with the right long-term fix: change the shebang to #!/bin/bash), not something to fold into this PR.

Address the 3 actionable comments in:

• 49ebce2 + a642962 on feat(build-tests): add Phase 1 dry-run regression suite for demo_build.sh (#146) #147: extended redaction (Authorization header + composer github-oauth) and the test.sh docstring path fix.
• 1a21699 on this PR: --image CLI precedence over fixture's INTEGRATION_IMAGE.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tools/build-tests/integration/run-scenario.sh (1)

113-119: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

Remove the unused PHP_VERSION_ABBR fixture assignment. demo_build.sh gets this value from the flex image, so the runner-side copy in inputs.env is dead and makes the fixture contract look stricter than it is.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tools/build-tests/integration/run-scenario.sh` around lines 113 - 119, Remove
the unused PHP_VERSION_ABBR fixture assignment from the scenario runner setup.
The copy in run-scenario.sh is dead because demo_build.sh derives this value
from the flex image, so update the inputs.env sourcing block to stop declaring
or relying on PHP_VERSION_ABBR and keep the fixture contract limited to the
values actually consumed there.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tools/build-tests/integration/run-scenario.sh`:
- Around line 168-172: The MariaDB and OpenEMR container launches in the
scenario runner are using mutable tags without forcing refresh, so warm agents
can reuse stale cached images. Update the docker run calls in the scenario setup
to either add --pull=always or perform an explicit docker pull before starting
the containers, making sure both the MariaDB startup and the OpenEMR startup
paths use the refreshed image behavior.

---

Nitpick comments:
In `@tools/build-tests/integration/run-scenario.sh`:
- Around line 113-119: Remove the unused PHP_VERSION_ABBR fixture assignment
from the scenario runner setup. The copy in run-scenario.sh is dead because
demo_build.sh derives this value from the flex image, so update the inputs.env
sourcing block to stop declaring or relying on PHP_VERSION_ABBR and keep the
fixture contract limited to the values actually consumed there.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a8a2867-2f42-4820-be87-8c05ffbf13c5

📥 Commits

Reviewing files that changed from the base of the PR and between 098ae80 and 1a21699.

📒 Files selected for processing (8)

• .github/workflows/build-tests-live.yml
• demo_build.sh
• tools/build-tests/fixtures/branch-pinned-master/expected/live-action-log.txt
• tools/build-tests/fixtures/release-packageserve/expected/live-action-log.txt
• tools/build-tests/fixtures/tag-pinned-with-data/expected/live-action-log.txt
• tools/build-tests/integration/run-all.sh
• tools/build-tests/integration/run-scenario.sh
• tools/build-tests/test.sh

✅ Files skipped from review due to trivial changes (3)

• tools/build-tests/fixtures/release-packageserve/expected/live-action-log.txt
• tools/build-tests/fixtures/branch-pinned-master/expected/live-action-log.txt
• tools/build-tests/fixtures/tag-pinned-with-data/expected/live-action-log.txt

🚧 Files skipped from review as they are similar to previous changes (4)

• .github/workflows/build-tests-live.yml
• tools/build-tests/integration/run-all.sh
• tools/build-tests/test.sh
• demo_build.sh

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify the runner's Docker CLI supports the proposed pull policy.
docker run --help | grep -F -- '--pull' || {
  echo "Docker CLI lacks docker run --pull support; use explicit docker pull commands instead." >&2
  exit 1
}

Repository: openemr/demo_farm_openemr

Length of output: 290

---

🌐 Web query:

Docker run --pull always documentation mutable tags cached local image behavior

💡 Result:

When you use the --pull always flag with the docker run command, Docker will unconditionally attempt to pull the specified image from the registry before creating and running the container, regardless of whether a version of that image already exists in your local cache [1][2]. This behavior is distinct from the default policy (missing), which only pulls the image if it is absent from the local cache [1]. Because --pull always forces a registry request, it effectively addresses the issue of mutable tags—where a tag like:latest or:stable may be updated in the registry—by ensuring that the local image cache is updated to match the current remote version before execution [1][2]. Key points regarding this behavior include: 1. Overwriting Local Images: If you have a locally built image with the same name and tag as a registry image, --pull always will overwrite your local image with the version fetched from the registry [1]. This can be problematic if you are attempting to test a locally built image that has not yet been pushed [1]. 2. Registry Efficiency: Modern Docker versions are optimized to minimize unnecessary downloads [3]. When you initiate a pull, Docker checks the manifest (often via a HEAD request) to determine if the local image digest matches the one in the registry [3]. If they match, the actual image layers are not re-downloaded [3]. 3. Alternative for Consistency: If you require absolute consistency and wish to avoid the ambiguity of mutable tags entirely, it is recommended to pull and run images by their immutable digest (e.g., image@sha256:...) rather than by tag [4][5][6]. Reference by digest guarantees that the container uses a specific, immutable version of the image regardless of what the tag points to in the registry [4][5].

Citations:

• 1: https://docs.docker.com/reference/cli/docker/container/run/
• 2: https://stackoverflow.com/questions/55941881/docker-run-vs-pull
• 3: Add option to docker pull to use local cache first without contacting Docker Hub docker/cli#6082
• 4: https://docs.docker.com/reference/cli/docker/image/pull/?highlight=docker&highlight=pull
• 5: docker run doesn't pull down latest image if the image exists locally moby/moby#13331
• 6: docker run doesn't pull down latest image if the image exists locally moby/moby#13331

---

Pull the mutable images before both runs. Add --pull=always (or an explicit docker pull) to the MariaDB and OpenEMR docker run calls so warm runners don’t reuse stale cached tags.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tools/build-tests/integration/run-scenario.sh` around lines 168 - 172, The
MariaDB and OpenEMR container launches in the scenario runner are using mutable
tags without forcing refresh, so warm agents can reuse stale cached images.
Update the docker run calls in the scenario setup to either add --pull=always or
perform an explicit docker pull before starting the containers, making sure both
the MariaDB startup and the OpenEMR startup paths use the refreshed image
behavior.