# 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