docs: improve standalone bootc installation documentation#841
Conversation
📝 WalkthroughWalkthroughThe standalone installation guide was reorganized into install, setup, development, bootable artifact, workflow, troubleshooting, cleanup, customization, and registry push sections. It replaces earlier guidance with revised commands and steps for ISO installation, bootc images, container testing, and registry publishing. ChangesStandalone installation guide rewrite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 markdownlint-cli2 (0.22.1)python/docs/source/getting-started/installation/service/standalone.mdmarkdownlint-cli2 v0.22.1 (markdownlint v0.40.0) 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. Comment |
Restructured the standalone installation guide to better serve both
end users and developers:
**User-focused improvements:**
- Simplified installation section with two clear methods:
1. Kickstart ISO creation (for fresh installs)
2. system-reinstall-bootc (for existing systems)
- Fixed curl commands to properly download and save files
- Fixed typo: system-reintall-bootc → system-reinstall-bootc
- Improved clarity and formatting throughout
- Added consistent terminology using {term}`operator`
**Developer-focused additions:**
- New comprehensive Development section covering:
- Building bootc images (single and multi-arch)
- Testing in containers with make bootc-run
- Creating bootable QCOW2 and ISO images
- Kickstart ISO generation with ARM64 support
- Fast iteration workflow with bootc-reload-app
- Troubleshooting common issues
- Cleanup procedures
- Registry publishing
The documentation now serves both audiences without confusion,
providing a clear path for users to deploy Jumpstarter and for
developers to modify and test the bootc image.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
mangelajo
force-pushed
the
fix-bootc-docs
branch
from
5fd3c4a to
b48ec6c
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@python/docs/source/getting-started/installation/service/standalone.md`:
- Around line 54-60: The port table is inconsistent with the API example, since
the MicroShift API is shown on 443 in the table but referenced as 6443
elsewhere. Update the standalone installation docs table in the port listing so
the API Server entry and the HTTPS/MicroShift API description match the `:6443`
example, and keep the descriptions in sync with the surrounding installation
guidance.
- Around line 21-25: Method 1 in the standalone installation docs should match
the working build flow by handling the CentOS redirect and using elevated
permissions for ISO creation. Update the commands in this section so the first
curl invocation follows redirects for CENTOS_ISO, and run mkksiso with sudo to
mirror the repo target behavior; use the existing standalone install command
sequence as the reference point.
🪄 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: 0178590a-8e0f-4b5a-81ed-5707f0d0cb69
📒 Files selected for processing (1)
python/docs/source/getting-started/installation/service/standalone.md
| | Port | Service | Description | | ||
| |------|---------|-------------| | ||
| | 80 | HTTP | MicroShift ingress | | ||
| | 443 | HTTPS | MicroShift API and ingress | | ||
| | 8880 | Config UI | Web configuration interface | | ||
| | 6443 | API Server | Kubernetes API (internal) | | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Align the port table with the API example.
The table says 443 serves the MicroShift API, but the next section points readers to :6443 for that API. Please make these entries consistent so operators know which port to open.
🤖 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 `@python/docs/source/getting-started/installation/service/standalone.md` around
lines 54 - 60, The port table is inconsistent with the API example, since the
MicroShift API is shown on 443 in the table but referenced as 6443 elsewhere.
Update the standalone installation docs table in the port listing so the API
Server entry and the HTTPS/MicroShift API description match the `:6443` example,
and keep the descriptions in sync with the surrounding installation guidance.
There was a problem hiding this comment.
right 443 is ingress only
There was a problem hiding this comment.
@mangelajo Thanks for confirming — that matches the concern. 443 should be documented as ingress only, and 6443 should remain the Kubernetes API port so the table stays consistent with the example.
There was a problem hiding this comment.
♻️ Duplicate comments (2)
python/docs/source/getting-started/installation/service/standalone.md (2)
54-60: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAlign the port table with the API example.
Line 57 still says 443 serves the MicroShift API and ingress, but the example below uses 6443 for the API. Please make one of them authoritative so operators open the right port.
Suggested fix
-| 443 | HTTPS | MicroShift API and ingress | +| 443 | HTTPS | MicroShift ingress |🤖 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 `@python/docs/source/getting-started/installation/service/standalone.md` around lines 54 - 60, The port table and API example are inconsistent about which port serves the MicroShift API. Update the standalone installation docs so the entries in the port table and the later API example agree, using the same authoritative port for the API; adjust the MicroShift ingress/API wording in the table or example accordingly so readers open the correct port.
21-25: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winMake the ISO build command match the working flow.
curlstill omits-L, so the CentOS redirect can fail, andmkksisois still run withoutsudo. That leaves this install path broken before the ISO is created.Suggested fix
- curl -o "${CENTOS_ISO}" "https://mirrors.centos.org/mirrorlist?path=/10-stream/BaseOS/x86_64/iso/${CENTOS_ISO}&redirect=1&protocol=https" + curl -L -o "${CENTOS_ISO}" "https://mirrors.centos.org/mirrorlist?path=/10-stream/BaseOS/x86_64/iso/${CENTOS_ISO}&redirect=1&protocol=https" ... - mkksiso kickstart.ks ${CENTOS_ISO} cs10-js-install.iso + sudo mkksiso kickstart.ks ${CENTOS_ISO} cs10-js-install.iso🤖 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 `@python/docs/source/getting-started/installation/service/standalone.md` around lines 21 - 25, The ISO build flow is still missing the redirect-following and privilege handling needed to complete successfully. Update the standalone install steps so the CentOS download command uses curl with redirect support, and run the mkksiso invocation with sudo as in the working flow. Use the standalone.md install snippet and the mkksiso/curl commands as the targets to adjust.
🤖 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.
Duplicate comments:
In `@python/docs/source/getting-started/installation/service/standalone.md`:
- Around line 54-60: The port table and API example are inconsistent about which
port serves the MicroShift API. Update the standalone installation docs so the
entries in the port table and the later API example agree, using the same
authoritative port for the API; adjust the MicroShift ingress/API wording in the
table or example accordingly so readers open the correct port.
- Around line 21-25: The ISO build flow is still missing the redirect-following
and privilege handling needed to complete successfully. Update the standalone
install steps so the CentOS download command uses curl with redirect support,
and run the mkksiso invocation with sudo as in the working flow. Use the
standalone.md install snippet and the mkksiso/curl commands as the targets to
adjust.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ed3322d1-a26b-477d-86b5-ef66a3811a65
📒 Files selected for processing (1)
python/docs/source/getting-started/installation/service/standalone.md
1 participant
Summary
Restructured the standalone installation guide to better serve both end users and developers by separating concerns and fixing several issues.
User-focused improvements
system-reinstall-bootc(for existing systems)-oflagssystem-reintall-bootc→system-reinstall-bootc{term}\operator``Developer-focused additions
make bootc-runmake bootc-reload-appBefore/After
Before: Mixed user and developer content, broken commands, unclear workflow
After: Clear separation - users get simple installation methods, developers get complete build/test/publish workflow
Test plan
🤖 Generated with Claude Code