LCORE-423: Add a section how to run lightspeed-stack image on MacOS

[are-ces]

Description

Edit README file to fix macOS image building guide

Type of change

• Refactor
• New feature
• Bug fix
• CVE fix
• Optimization
• Documentation Update
• Configuration Update
• Bump-up service version
• Bump-up dependent library
• Bump-up library or tool used for development (does not change the final image)
• CI configuration change
• Konflux configuration change
• Unit tests improvement
• Integration tests improvement
• End to end tests improvement

Related Tickets & Documents

• Related Issue # 423
• Closes # 423

Checklist before requesting a review

• I have performed a self-review of my code.
• PR has passed all pre-merge test jobs.
• If it is a core feature, I have added thorough tests.

Testing

I have tested image building and run on macOS Tahoe 26.1

Summary by CodeRabbit

• Documentation
  • Expanded macOS-specific documentation for ARM64 architecture with clarified guidance differentiating Docker Compose and Podman Compose compatibility, including notes about emulation considerations on macOS systems
  • Reorganized Library Mode section with a dedicated formal macOS header to improve documentation structure, navigation, and clarity for macOS users

[coderabbitai]

Walkthrough

README.md updated with macOS-specific guidance for ARM64 container building, noting incompatibility of podman compose emulation and recommending docker compose instead. Library Mode section header standardized from inline label to formal markdown header.

Changes

Cohort / File(s)	Change Summary
Documentation updates README.md	Adds macOS ARM64 guidance clarifying podman compose limitations and suggesting docker compose; formalizes Library Mode macOS instructions with proper markdown header

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

• Documentation-only changes with minor structural formatting updates
• No logic, no exported entities affected
• Straightforward readability improvements

Possibly related PRs

• LCORE-431: how to build the lightspeed core image #391: Modifies the same README sections covering container-building documentation and macOS-specific guidance for both podman/docker compose and Library Mode headers.

Suggested reviewers

• tisnik
• radofuchs
• matysek

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding macOS-specific guidance to the README for running the lightspeed-stack image, which aligns perfectly with the file changes summarized.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

README.md (2)

598-608: Clarify what "will not work" means.

Line 600 uses vague language about podman compose incompatibility. Specify the actual failure mode—does emulation hang, error out, produce incorrect results, or cause performance issues? This helps macOS users quickly identify if they're experiencing the described problem and know how to resolve it.

Consider updating line 600 to something like:

-Emulation of platform amd64 will not work with `podman compose up --build` command.
+Emulation of platform amd64 on macOS with `podman compose up --build` may fail or hang.

Or provide more specific details if you know the exact error behavior observed during testing.

---

634-642: Explain the mount option difference between Library Mode sections.

The macOS section (lines 636–639) uses :ro (read-only) mounts, while the generic example above it (lines 628–629) uses :Z (SELinux relabel). Adding a brief comment explaining why macOS requires different mount flags would help users understand when to use each and prevent copy/paste errors across different platforms.

Consider adding a clarifying comment:

 #### macOS
+<!-- Use read-only (`:ro`) mounts on macOS instead of SELinux context (`:Z`) -->
 ```bash
 podman run \

Or update the documentation narrative above the code block to note the platform-specific mount difference.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between db45d8c and dc2a0d3.

📒 Files selected for processing (1)

• README.md (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
• GitHub Check: build-pr
• GitHub Check: e2e_tests (azure)
• GitHub Check: e2e_tests (ci)

[tisnik]

LGTM