Skip to content

fix(qemu): add overlay support to Windows and Linux containers#1255

Open
NikkeTryHard wants to merge 2 commits intotrycua:mainfrom
NikkeTryHard:fix/qemu-overlay-support
Open

fix(qemu): add overlay support to Windows and Linux containers#1255
NikkeTryHard wants to merge 2 commits intotrycua:mainfrom
NikkeTryHard:fix/qemu-overlay-support

Conversation

@NikkeTryHard
Copy link
Copy Markdown

@NikkeTryHard NikkeTryHard commented Apr 1, 2026

Summary

  • Detect overlay mode in Windows and Linux QEMU container entrypoints
  • When /golden is mounted read-only and /storage is empty, populate storage via hard links (cp -al) for copy-on-write semantics
  • Fall back to cp -a when hard links are not supported (cross-filesystem mounts)

Test plan

  • Build Linux container, run with /golden:ro + empty /storage -- logs show "Overlay mode detected", VM boots from linked files
  • Build Windows container, same overlay test -- overlay detected, windows.boot not re-created (already present from golden)
  • Run without /golden mounted -- no overlay message, normal boot path unchanged
  • Hard-link fallback: mount /golden and /storage on different filesystems -- falls back to full copy

Closes #699
Supersedes #730

Summary by CodeRabbit

  • New Features
    • Storage initialization now includes automatic overlay mode support for both Linux and Windows environments. The system intelligently detects when template images are available and efficiently initializes storage using optimized copy-on-write techniques when supported. Automatic fallback to standard copy operations ensures compatibility across all system configurations.

@vercel
Copy link
Copy Markdown
Contributor

vercel bot commented Apr 1, 2026

@NikkeTryHard is attempting to deploy a commit to the Cua Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Apr 1, 2026

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fb9570ac-3637-42ef-858e-7b712786d7e5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Container entrypoints now detect overlay mode—when /golden exists and /storage is empty—and initialize /storage from /golden using hard-link copies with fallback to full attribute-preserving copies, enabling isolated test sessions from a shared golden image.

Changes

Cohort / File(s) Summary
Container Overlay Initialization
libs/qemu-docker/linux/src/entry.sh, libs/qemu-docker/windows/src/entry.sh
Added overlay mode detection and setup logic that checks for /golden directory and empty /storage, then populates /storage using hard-link copies (cp -al) with fallback to full recursive copy (cp -a), with corresponding status messaging.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

A rabbit hops through storage bright,
With golden copies hard-linked tight—
No duplicates, just shared delight,
Each test gets its own pristine sight! 🐰✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'fix(qemu): add overlay support to Windows and Linux containers' clearly and concisely summarizes the main change: adding overlay support to QEMU containers for both Windows and Linux.
Linked Issues check ✅ Passed The PR implements the core overlay detection and setup requirements from issue #699: detects when /golden is mounted and /storage is empty, uses hard links (cp -al) with fallback to cp -a, and runs before existing VM startup logic.
Out of Scope Changes check ✅ Passed All changes are scoped to adding overlay initialization in both Linux and Windows entry.sh scripts; no unrelated modifications or refactoring are present.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
libs/qemu-docker/linux/src/entry.sh (1)

15-25: Consider extracting shared overlay logic to reduce duplication.

The overlay setup block is identical in both Windows and Linux entrypoints. If the logic evolves (e.g., adding logging, metrics, or additional validation), both files must be updated in sync.

Consider extracting this into a shared script (e.g., /run/overlay-setup.sh) that both entrypoints source or invoke.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@libs/qemu-docker/linux/src/entry.sh` around lines 15 - 25, Extract the
duplicated overlay setup shell block into a reusable script (e.g., create an
executable overlay-setup.sh that encapsulates the if [ -d "/golden" ] && [ -z
"$(ls -A /storage 2>/dev/null)" ] check, the cp -al fallback to cp -a, and the
echo messages), then replace the duplicated code in
libs/qemu-docker/linux/src/entry.sh with a single invocation or source of
overlay-setup.sh; ensure the new script returns non-zero on fatal errors and
preserves existing behavior and messages so both Linux and the Windows
entrypoint can call the same script.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@libs/qemu-docker/linux/src/entry.sh`:
- Around line 15-25: The fallback cp -a in entry.sh has no error handling, so if
it fails the script continues with incomplete /storage; update the overlay setup
block (the cp -al fallback path) to check the exit status of the cp -a command
and on failure emit a clear error message (echo) and exit with non-zero status;
ensure the messages mirror the existing "Hard links not supported, falling back
to full copy..." and "Overlay setup complete (full copy)." flow but add a
failure branch that logs the cp error and calls exit 1 so the container/VM fails
fast instead of booting with bad state.

In `@libs/qemu-docker/windows/src/entry.sh`:
- Around line 15-25: The fallback copy in entry.sh silently continues if cp -a
/golden/. /storage/ fails and the initial empty-check using ls -A masks the case
where /storage does not exist; update the overlay setup to first validate that
/storage exists and is a writable directory (replace the ls -A test with an
explicit existence/permission check), then run the cp -a fallback and
immediately test its exit status—on failure log a descriptive error including
the cp error, remove any partially copied content or restore /storage to a safe
state, and exit non‑zero to prevent booting with an incomplete overlay; ensure
these checks are applied around the existing if-block that performs cp -al and
cp -a so both hard-link and fallback paths are covered.

---

Nitpick comments:
In `@libs/qemu-docker/linux/src/entry.sh`:
- Around line 15-25: Extract the duplicated overlay setup shell block into a
reusable script (e.g., create an executable overlay-setup.sh that encapsulates
the if [ -d "/golden" ] && [ -z "$(ls -A /storage 2>/dev/null)" ] check, the cp
-al fallback to cp -a, and the echo messages), then replace the duplicated code
in libs/qemu-docker/linux/src/entry.sh with a single invocation or source of
overlay-setup.sh; ensure the new script returns non-zero on fatal errors and
preserves existing behavior and messages so both Linux and the Windows
entrypoint can call the same script.
🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 39868817-57f4-4c96-8c2f-dbb60689eaa8

📥 Commits

Reviewing files that changed from the base of the PR and between 8e6fa30 and e06ba05.

📒 Files selected for processing (2)
  • libs/qemu-docker/linux/src/entry.sh
  • libs/qemu-docker/windows/src/entry.sh

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

# Add overlay support to cua-qemu-windows container

1 participant