docs(usb-creator): document creating a bootable drive - #524
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughThe bootable media guide now uses USB Creator terminology and documents the complete process for creating an Unraid USB drive, configuring the server to boot, and resolving common installation and licensing issues. ChangesUSB Creator bootable media guide
Estimated code review effort: 2 (Simple) | ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
unraid-docs | 4966219 | Commit Preview URL Branch Preview URL |
Aug 07 2026, 02:33 PM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
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 `@docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdx`:
- Around line 121-125: Update the BIOS/UEFI setup step in the bootable-media
instructions to avoid presenting HVM and IOMMU as universally required for
booting Unraid. State that HVM is needed only when using virtual machines, and
IOMMU only when required for device passthrough, while preserving the existing
reference to the configuration details.
- Around line 108-112: Update the Linux instructions in the bootable-media setup
section to copy make_bootable_linux to local storage before unmounting the USB
drive, then run the copied script with sudo from its local path. Keep the
Windows and macOS instructions unchanged.
🪄 Autofix
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: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: de106dcd-1ae3-4af4-b4d8-3c1d0b344611
📒 Files selected for processing (1)
docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdx
Comment on lines
+108
to
+112
| UEFI systems can boot from the drive without any extra step. For an older BIOS-only system, run the boot script from the root of the USB drive: | ||
|
|
||
| - **Windows:** Right-click `make_bootable.bat` and select **Run as administrator**. | ||
| - **macOS:** Double-click `make_bootable_mac` and enter your administrator password when prompted. | ||
| - **Linux:** Unmount the USB drive. Then run `sudo bash ./make_bootable_linux`. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Copy the Linux script before unmounting the USB drive.
Line 112 unmounts the USB drive before it runs ./make_bootable_linux. The relative path cannot resolve after the drive is unmounted. This blocks legacy BIOS setup from Linux. Match the manual method by copying the script to local storage before unmounting the drive.
Proposed fix
-- **Linux:** Unmount the USB drive. Then run `sudo bash ./make_bootable_linux`.
+- **Linux:** Copy `make_bootable_linux` to local storage. Unmount the USB drive. Then run `sudo bash ./make_bootable_linux` from the directory that contains the copied script.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| UEFI systems can boot from the drive without any extra step. For an older BIOS-only system, run the boot script from the root of the USB drive: | |
| - **Windows:** Right-click `make_bootable.bat` and select **Run as administrator**. | |
| - **macOS:** Double-click `make_bootable_mac` and enter your administrator password when prompted. | |
| - **Linux:** Unmount the USB drive. Then run `sudo bash ./make_bootable_linux`. | |
| UEFI systems can boot from the drive without any extra step. For an older BIOS-only system, run the boot script from the root of the USB drive: | |
| - **Windows:** Right-click `make_bootable.bat` and select **Run as administrator**. | |
| - **macOS:** Double-click `make_bootable_mac` and enter your administrator password when prompted. | |
| - **Linux:** Copy `make_bootable_linux` to local storage. Unmount the USB drive. Then run `sudo bash ./make_bootable_linux` from the directory that contains the copied script. |
🤖 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 `@docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdx`
around lines 108 - 112, Update the Linux instructions in the bootable-media
setup section to copy make_bootable_linux to local storage before unmounting the
USB drive, then run the copied script with sudo from its local path. Keep the
Windows and macOS instructions unchanged.
Comment on lines
+121
to
+125
| 1. Insert the prepared USB drive into the server. | ||
| 2. Open the server's BIOS or UEFI settings. | ||
| 3. Set the USB drive as the first boot device. | ||
| 4. Enable %%hardware virtualization|hvm%% features, including %%IOMMU|iommu%%. See [HVM & IOMMU configuration](../../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx#hvm--iommu-what-they-enable) for details. | ||
| 5. Save the BIOS settings and restart the server. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make virtualization settings conditional on the intended use.
Line 124 presents HVM and IOMMU as required to boot Unraid. They are not required for a basic server boot. Require HVM only for virtual machines. Require IOMMU when device passthrough needs it.
Proposed fix
-4. Enable %%hardware virtualization|hvm%% features, including %%IOMMU|iommu%%. See [HVM & IOMMU configuration](../../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx#hvm--iommu-what-they-enable) for details.
+4. If you plan to run %%VMs|vm%%, enable %%hardware virtualization|hvm%%. If you plan to use device passthrough, also enable %%IOMMU|iommu%%. See [HVM & IOMMU configuration](../../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx#hvm--iommu-what-they-enable) for details.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 1. Insert the prepared USB drive into the server. | |
| 2. Open the server's BIOS or UEFI settings. | |
| 3. Set the USB drive as the first boot device. | |
| 4. Enable %%hardware virtualization|hvm%% features, including %%IOMMU|iommu%%. See [HVM & IOMMU configuration](../../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx#hvm--iommu-what-they-enable) for details. | |
| 5. Save the BIOS settings and restart the server. | |
| 1. Insert the prepared USB drive into the server. | |
| 2. Open the server's BIOS or UEFI settings. | |
| 3. Set the USB drive as the first boot device. | |
| 4. If you plan to run %%VMs|vm%%, enable %%hardware virtualization|hvm%%. If you plan to use device passthrough, also enable %%IOMMU|iommu%%. See [HVM & IOMMU configuration](../../using-unraid-to/create-virtual-machines/overview-and-system-prep.mdx#hvm--iommu-what-they-enable) for details. | |
| 5. Save the BIOS settings and restart the server. |
🤖 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 `@docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdx`
around lines 121 - 125, Update the BIOS/UEFI setup step in the bootable-media
instructions to avoid presenting HVM and IOMMU as universally required for
booting Unraid. State that HVM is needed only when using virtual machines, and
IOMMU only when required for device passthrough, while preserving the existing
reference to the configuration details.
Eli Bosley (elibosley)
added a commit
that referenced
this pull request
Aug 7, 2026
## Summary This follow-up to #524 updates the screenshot-led guide for creating a new Unraid USB boot device with the USB Creator. ## Why This Exists The page previously provided only a high-level six-step outline and included stale USB-only guidance. Users needed current boot-device choices, a clear warning about erasing the selected drive, and guidance for first boot and older BIOS-only systems. ## Resolution Expand the existing Create an Unraid USB drive page with the five merged USB Creator screenshots, step-by-step UI actions, optional server/network customization notes, current flash-versus-internal-boot guidance for Unraid 7.3+, UEFI/legacy BIOS instructions, and troubleshooting. ## Reviewer Considerations - Confirm the stable-release guidance and the optional development-image warning match the intended USB Creator experience. - Check the platform-specific legacy BIOS script names and first-boot guidance. - Confirm that internal boot is described as an onboarding choice after the initial USB boot. - Confirm that the USB Creator guidance does not impose a drive-capacity range; the remaining 32 GB reference applies only to Windows FAT32 formatting for manual installs. - The manual installation section remains in place; this change improves the recommended automated path rather than replacing it. - Screenshot references target the assets merged in `origin/main` by #523. ## Behavior Changes Documentation-only. Users now see a complete path from USB Creator download through first boot, with flash boot or internal boot choices, troubleshooting for missing drives and boot failures, and GUID licensing guidance. ## Implementation Summary - Renamed the page label/title to Create an Unraid USB drive. - Expanded the automated install section with five screenshot-linked workflow steps. - Documented optional Server name, Wi-Fi, and Network customization. - Removed the outdated 4–32 GB recommendation and separated the Windows FAT32 formatting limit from USB Creator capacity guidance. - Added the Unraid 7.3+ internal boot path and removed unrelated virtualization/IOMMU setup from the USB creation procedure. - Added UEFI versus BIOS-only boot guidance and troubleshooting. ## Verification - `./node_modules/.bin/remark docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdx --quiet --frail` - `./node_modules/.bin/prettier --check docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdx` - `git diff --check` - Verified all five screenshot paths resolve against `origin/main`. - Full Docusaurus build not run because repository guidance discourages it for routine docs edits. ## Risk Low. Documentation-only change; the page links to existing screenshot assets and leaves the manual install instructions intact.
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.
Summary
This adds a complete, screenshot-led guide for creating a new Unraid USB boot device with the USB Creator.
Why This Exists
The page previously provided only a high-level six-step outline and included stale USB-only guidance. Users needed the actual Creator flow, current boot-device choices, a clear warning about erasing the selected drive, and guidance for first boot and older BIOS-only systems.
Resolution
Expand the existing Create an Unraid USB drive page with the five merged USB Creator screenshots, step-by-step UI actions, optional server/network customization notes, current flash-versus-internal-boot guidance for Unraid 7.3+, UEFI/legacy BIOS instructions, and troubleshooting.
Reviewer Considerations
origin/mainby docs: refresh USB Creator setup screenshots #523.Behavior Changes
Documentation-only. Users now see a complete path from USB Creator download through first boot, with flash boot or internal boot choices, troubleshooting for missing drives and boot failures, and GUID licensing guidance.
Implementation Summary
Verification
./node_modules/.bin/remark docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdx --quiet --frail./node_modules/.bin/prettier --check docs/unraid-os/getting-started/set-up-unraid/create-your-bootable-media.mdxgit diff --checkorigin/main.Risk
Low. Documentation-only change; the page links to existing screenshot assets and leaves the manual install instructions intact.