293 lines
6.9 KiB
Markdown
Executable File
293 lines
6.9 KiB
Markdown
Executable File
# QUICKSTART — DriveStage in 5 Minutes
|
|
|
|
**Author:** Jeremy Anderson <info@dcos.net> — [dcos.net](https://dcos.net)
|
|
|
|
This guide provisions a bootable DriveStage stick in under five minutes.
|
|
|
|
**Prerequisites:**
|
|
- A Linux machine (any modern distribution)
|
|
- A USB drive (8 GB or larger)
|
|
- Root access via `sudo`
|
|
|
|
---
|
|
|
|
## Step 1 — Install system dependencies
|
|
|
|
The engine requires standard Linux utilities. Install by distribution:
|
|
|
|
### Debian / Ubuntu
|
|
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install -y \
|
|
parted dosfstools e2fsprogs \
|
|
grub-pc-bin grub-efi-amd64-bin \
|
|
util-linux rsync tar \
|
|
smartmontools
|
|
```
|
|
|
|
### Fedora
|
|
|
|
```bash
|
|
sudo dnf install -y \
|
|
parted dosfstools e2fsprogs \
|
|
grub2-pc grub2-efi-x64 grub2-tools grub2-common \
|
|
util-linux rsync tar \
|
|
smartmontools
|
|
```
|
|
|
|
### Arch Linux
|
|
|
|
```bash
|
|
sudo pacman -S --needed \
|
|
parted dosfstools e2fsprogs \
|
|
grub efibootmgr \
|
|
util-linux rsync tar \
|
|
smartmontools
|
|
```
|
|
|
|
---
|
|
|
|
## Step 2 — Obtain the engine
|
|
|
|
### From the tarball
|
|
|
|
```bash
|
|
tar xzf drivestage-0.4.0.tar.gz
|
|
cd drivestage
|
|
chmod +x scripts/blkstage.sh
|
|
```
|
|
|
|
### From git
|
|
|
|
```bash
|
|
git clone https://git.dcos.net/dcosnet/DriveStage.git
|
|
cd drivestage
|
|
chmod +x scripts/blkstage.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Step 3 — Identify the USB drive
|
|
|
|
Plug in the USB drive and identify the device node:
|
|
|
|
```bash
|
|
lsblk
|
|
```
|
|
|
|
Locate the device matching your USB drive's capacity. The device is
|
|
typically `/dev/sdb` or `/dev/sdc`. **Verify the device name carefully**
|
|
— the next step erases all data on the target.
|
|
|
|
For interactive selection, run the engine without a device argument and
|
|
it lists removable candidates:
|
|
|
|
```bash
|
|
sudo ./scripts/blkstage.sh setup
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4 — Provision the drive
|
|
|
|
**This erases all data on the target drive.** Verify the device name.
|
|
|
|
```bash
|
|
sudo ./scripts/blkstage.sh setup /dev/sdX
|
|
```
|
|
|
|
Replace `/dev/sdX` with your device (for example, `/dev/sdb`).
|
|
|
|
The engine executes the following sequence:
|
|
|
|
1. Requests typed confirmation (you type the device basename, e.g. `sdb`)
|
|
2. Wipes existing filesystem signatures
|
|
3. Creates a GPT partition table with three partitions:
|
|
- **ESP** (FAT32, 512 MB) — UEFI GRUB binaries
|
|
- **BIOS Boot** (1 MB, unformatted) — GRUB i386-pc embedding
|
|
- **Payloads** (ext4, remainder) — ISOs and rootfs data
|
|
4. Formats each partition
|
|
5. Installs GRUB2 for both UEFI (`x86_64-efi`) and BIOS (`i386-pc`)
|
|
6. Writes the auto-scan `grub.cfg`
|
|
7. Creates the payload directory structure
|
|
|
|
At completion the drive is bootable and empty.
|
|
|
|
---
|
|
|
|
## Step 5 — Add payloads
|
|
|
|
The payload partition mounts at `/mnt/drivestage/payload/`. Two methods:
|
|
|
|
### Method A — `deploy` subcommand
|
|
|
|
```bash
|
|
# ISO — copy and done
|
|
sudo ./scripts/blkstage.sh deploy /dev/sdX ~/Downloads/ubuntu-24.04-desktop-amd64.iso
|
|
|
|
# Additional ISOs
|
|
sudo ./scripts/blkstage.sh deploy /dev/sdX ~/Downloads/archlinux-2026.08.01-x86_64.iso
|
|
|
|
# Rootfs tarball — copy and extract in one step
|
|
sudo ./scripts/blkstage.sh deploy /dev/sdX ~/Downloads/rootfs-arch-x86_64.tar.gz
|
|
```
|
|
|
|
### Method B — Direct copy
|
|
|
|
```bash
|
|
# Payload partition is mounted at /mnt/drivestage/payload/
|
|
cp ~/Downloads/*.iso /mnt/drivestage/payload/payloads/isos/
|
|
cp ~/Downloads/rootfs-*.tar.gz /mnt/drivestage/payload/payloads/rootfs_tarballs/
|
|
|
|
# Extract tarballs (ISOs require no extraction)
|
|
sudo ./scripts/blkstage.sh scan /dev/sdX
|
|
```
|
|
|
|
### Payload directory layout
|
|
|
|
```
|
|
/mnt/drivestage/payload/payloads/
|
|
├── isos/ ← .iso files (Ubuntu, Arch, Fedora, ...)
|
|
├── rootfs_tarballs/ ← .tar.gz files (extracted on first scan)
|
|
├── rootfs/ ← pre-extracted rootfs directories
|
|
├── images/ ← .img / .raw files (experimental)
|
|
└── overlay/ ← reserved for overlayfs persistence
|
|
```
|
|
|
|
---
|
|
|
|
## Step 6 — List registered payloads
|
|
|
|
```bash
|
|
sudo ./scripts/blkstage.sh list /dev/sdX
|
|
```
|
|
|
|
Sample output:
|
|
|
|
```
|
|
[*] Registered payloads on this drive:
|
|
|
|
ISOs:
|
|
ubuntu-24.04-desktop-amd64.iso 4.7 GB
|
|
archlinux-2026.08.01-x86_64.iso 1.1 GB
|
|
|
|
RootFS Tarballs:
|
|
rootfs-arch-x86_64.tar.gz 850 MB
|
|
|
|
Extracted RootFS:
|
|
rootfs-arch-x86_64 1.2 GB
|
|
```
|
|
|
|
---
|
|
|
|
## Step 7 — Boot
|
|
|
|
```bash
|
|
sudo umount /mnt/drivestage/payload/boot/efi 2>/dev/null
|
|
sudo umount /mnt/drivestage/payload 2>/dev/null
|
|
sudo eject /dev/sdX
|
|
```
|
|
|
|
Boot from the USB on any machine. GRUB presents the auto-discovered
|
|
payload menu:
|
|
|
|
```
|
|
====================================================
|
|
DriveStage — Auto-Scan Payload Menu
|
|
Partition UUID: a1b2c3d4-5678-90ef-1234-567890abcdef
|
|
====================================================
|
|
|
|
ubuntu-24.04-desktop-amd64.iso [casper]
|
|
archlinux-2026.08.01-x86_64.iso [arch]
|
|
rootfs-arch-x86_64 [arch-rootfs]
|
|
|
|
Drop to GRUB command line
|
|
Reboot system
|
|
Halt system
|
|
```
|
|
|
|
Select an entry to boot.
|
|
|
|
---
|
|
|
|
## Adding payloads after initial setup
|
|
|
|
No re-provisioning required:
|
|
|
|
```bash
|
|
sudo mount /dev/sdX3 /mnt/drivestage/payload
|
|
cp ~/Downloads/fedora-workstation.iso /mnt/drivestage/payload/payloads/isos/
|
|
sudo umount /mnt/drivestage/payload
|
|
```
|
|
|
|
**ISOs require no `scan` command.** GRUB discovers them at boot. The
|
|
`scan` command applies only to tarballs, which require host-side
|
|
extraction (GRUB has no untar capability at boot time).
|
|
|
|
---
|
|
|
|
## Optional — Build the GUI
|
|
|
|
```bash
|
|
cd gui/
|
|
|
|
# Install Rust via rustup if absent
|
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
|
source ~/.cargo/env
|
|
|
|
cargo build --release
|
|
./target/release/drivestage-gui
|
|
```
|
|
|
|
The GUI provides a setup wizard, payload manager, bootloader switcher,
|
|
menu editor, and diagnostics.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "Refusing: '/dev/sdX' contains mounted filesystem (likely your OS disk)"
|
|
|
|
The selected device hosts a mounted OS partition. Re-run `lsblk` and
|
|
select the actual USB drive.
|
|
|
|
### GRUB menu does not display a recently added ISO
|
|
|
|
Verify the file resides in `payloads/isos/`. The auto-scan reads
|
|
specific subdirectories. Run `sudo ./scripts/blkstage.sh list /dev/sdX`
|
|
to confirm.
|
|
|
|
### An ISO fails to boot
|
|
|
|
The auto-scan recognizes 30+ distro patterns. Unrecognized ISOs
|
|
chainload via GRUB's `loopback.cfg`. If chainload fails, add a manual
|
|
`menuentry` to `/boot/grub/custom.cfg` on the payload partition. Refer
|
|
to `BLOG.md` for the architecture.
|
|
|
|
### Drive does not boot on BIOS hardware
|
|
|
|
Confirm `setup` was run — it installs GRUB's `i386-pc` BIOS boot code.
|
|
To reinstall:
|
|
|
|
```bash
|
|
sudo ./scripts/blkstage.sh setup /dev/sdX
|
|
```
|
|
|
|
This re-partitions and formats. Back up payloads first.
|
|
|
|
### Drive does not boot on a Mac
|
|
|
|
Macs use 64-bit EFI. The `--removable` flag in `grub-install
|
|
--target=x86_64-efi` writes `/EFI/BOOT/BOOTX64.EFI`, which Macs boot.
|
|
Hold Option at startup and select "EFI Boot."
|
|
|
|
---
|
|
|
|
## Next steps
|
|
|
|
- [`BLOG.md`](BLOG.md) — design rationale and architecture deep-dive
|
|
- [`README.md`](README.md) — full feature list and repository layout
|
|
- `./scripts/blkstage.sh --help` — complete CLI reference
|
|
- [`gui/README.md`](gui/README.md) — GUI build and usage
|