docs: docker migration planning (tracking #790)#796
Draft
bradymiller wants to merge 11 commits into
Draft
Conversation
Living doc tracking the migration of OpenEMR docker images and their build / test pipelines from openemr-devops to openemr core. Captures the agreed-upon repository layout (per-rel-branch Dockerfile + build script + BATS dir, master orchestrates schedule), what moves where, the phased plan, and the open decisions. Posted alongside openemr#790 where discussion happens. This file gets edited as PRs land and the plan evolves. The doc lives in docs/ to match the existing convention used by docs/release-automation-plan.md. Assisted-by: Claude Code
Previous version recommended consolidating build-322/build-323/ build-edge into a single matrix-driven build-flex.yml (and similar for test-flex-*). Reverting that recommendation -- the per-variant split aligns with the recently refactored "add/remove alpine version = file add/delete" model, and matches the broader migration philosophy of one workflow file per artifact lifecycle. Net effect: phase 1b becomes pure lift-and-shift for the flex workflows (build-flex-core + the three per-alpine callers + the three per-alpine test files) rather than restructuring during the move. Drops phase 1b from ~1.5 days to ~1 day. Assisted-by: Claude Code
Maintainer is driving the migration end-to-end; phase ownership isn't open. Other feedback items (path naming, credential scope, inventory completeness) remain. Assisted-by: Claude Code
Previous layout had both test-release.yml (new) and test-production.yml (renamed devops file) on master and rel branches -- two workflows doing the same thing, PR validation of the release Dockerfile. Collapse to a single test-release.yml: matches build-release.yml naming, matches the docker/openemr/release/ directory name, drops the "production vs release" inconsistency. Devops's existing test-production.yml migrates as test-release.yml during the move. Assisted-by: Claude Code
…nment
Updates the design to have master's release-cron.yml control which
docker tags each rel branch pushes (via workflow_dispatch -f tags=...
inputs), instead of each rel branch hardcoding its own tag list.
Consequences captured in the doc:
* build-release.yml is now byte-identical across master and every
rel branch -- only the Dockerfile and BATS tests diverge.
* Tag promotion (rotating latest, bumping next) becomes a one-line
edit on master's orchestrator. No PR against a rel branch.
* Branch-cut drops from 5 steps to 3: cut, pin Dockerfile, add
fan-out entry on master.
* Orchestrator gains per-branch boolean inputs so manual dispatches
can selectively skip branches (cron runs ignore inputs and run
everything).
* Rel branch's build-release.yml exposes a `tags` text input with
default "manual-test" -- safe sentinel for ad-hoc dispatches that
won't clobber production tags.
Also flags a name collision in phase 3: devops's existing
build-release.yml (release packaging / tarballs) is distinct from the
docker build-release.yml proposed here. Needs migration under a
different name like package-release.yml.
Assisted-by: Claude Code
Two refinements to the orchestrator design: 1. Switch release-cron.yml to a single inline matrix with include / exclude string inputs, rather than per-branch boolean inputs and hardcoded fan-out steps. Adding a rel branch is now a one-row matrix diff; rotating "latest" is a one-line diff. Scales past GitHub's 10-input cap. Automation can edit the matrix as flat data. 2. Define the dated-tag rule in build-release.yml: any tag that's digits-and-dots-only (e.g. "8.1.0", "8.0.0.3") gets a sibling "<tag>-YYYY-MM-DD" pushed alongside. Floating tags (dev, next, latest, manual-test) don't. Date format matches the current devops convention (date +'%Y-%m-%d' from build-openemr.yml). Living the rule in build-release.yml means the orchestrator matrix stays purely declarative -- it carries only logical tags. Assisted-by: Claude Code
Apply the docker- prefix convention across the doc:
build-release.yml -> docker-build-release.yml
build-flex-core.yml -> docker-build-flex-core.yml
build-{322,323,edge,binary}.yml -> docker-build-{322,323,edge,binary}.yml
test-release.yml -> docker-test-release.yml
test-{flex-322,flex-323,flex-edge,binary,bats,core}.yml -> docker-test-*.yml
test-container-functionality.yml -> docker-test-container-functionality.yml
release-cron.yml -> docker-release-cron.yml
Plus existing openemr core file:
hadolint.yml -> docker-lint-hadolint.yml
(includes README badge URL fix; check name "Dockerfile Linting" is
unaffected since it's set via name:, not derived from filename)
docker-compose-lint.yml stays as-is (already self-describing).
Side benefit: the name collision with devops's existing
build-release.yml (release packaging / tarballs) resolves naturally
since the new docker build is docker-build-release.yml.
What-moves-where table updated to show source vs. destination
filename divergence clearly. Phase 1b expanded to include the
hadolint rename + badge update.
Assisted-by: Claude Code
Move all docker BATS dirs into a tests/bats/docker/ subdirectory: tests/bats/flex/ -> tests/bats/docker/flex/ tests/bats/binary/ -> tests/bats/docker/binary/ tests/bats/release/ -> tests/bats/docker/release/ Mirrors the docker- workflow prefix convention. Self-documenting hierarchy that leaves room for future non-docker BATS categories without inconsistency. Matches the "everything docker is grouped together" theme. tests/bats/openemr-cmd/ stays where it is in openemr-devops (different repo, different scope; can reorganize on its own timeline if desired). Assisted-by: Claude Code
rel-811 doesn't exist yet -- it'll be cut from master in the future via the standard branch-cut process. Until then: master -> dev, next rel-810 -> 8.1.0, latest rel-800 -> 8.0.0 rel-704 -> 7.0.4 Updates: tag-mapping list, orchestrator matrix (rel-811 row removed, master gains "next", rel-810 gains "latest", rel-800 drops "latest"), and the two table rows where /docker/openemr/8.1.1/ and /tests/bats/8.1.1/ now correctly go to openemr master (since 8.1.1 tracks OPENEMR_VERSION=master in the devops Dockerfile -- it's the dev/next build, not a real rel-811). Added a note next to the tag list pointing at the branch-cut process for when rel-811 does land. Assisted-by: Claude Code
openemr core uses docker/<purpose>/ convention (see existing docker/production/, docker/development-easy/, docker/library/). Devops uses docker/openemr/<purpose>/ which makes sense in that repo (openemr is one of many concerns there). In openemr core there's no need for the extra openemr/ layer -- everything is openemr. Update destination paths accordingly: docker/openemr/release/ -> docker/release/ docker/openemr/flex/ -> docker/flex/ docker/openemr/binary/ -> docker/binary/ The existing docker/production/docker-compose.yml is a compose recipe for running the production image locally (a separate concern from docker/release/ which holds the Dockerfile that builds the image). They coexist cleanly. Decision item 2 in the "Decisions to lock" section is resolved as part of phase 1a. Assisted-by: Claude Code
…orchestrator Combines the cron + orchestrator concepts into a single descriptive filename. The workflow handles both the scheduled tick and the fan-out logic, so the merged name fits both halves. Also fixes a stale "run_rel_XYZ boolean input" reference in the branch-cut process steps -- leftover from the earlier per-branch boolean design that was replaced with the matrix-driven shape. Assisted-by: Claude Code
Member
Author
|
Companion tracking PR in core repo: openemr/openemr#12482 (carries the actual workflow code as it lands phase by phase). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Living planning doc + tracking branch for the docker migration proposed in #790.
Draft / WIP -- not for merge until the migration is far enough along that this doc reflects landed state rather than aspirational design. Open for visibility so anyone interested can see the current shape, comment on edges, or suggest changes.
What's in this PR
What's NOT in this PR
This branch holds only the planning doc. Actual workflow / Dockerfile / BATS migrations land as separate PRs against `openemr/openemr` per the phased plan in the doc.
How to follow along
Discussion happens in #790. Phase-by-phase landing PRs (against `openemr/openemr`) will reference back here. As they land, this doc gets updated to reflect actual state, and the PR description in #790 is kept in sync with the doc.
The companion tracking PR in `openemr/openemr` carries the actual workflow code as it lands. Find it via the cross-link in #790.