Skip to content

Create a USB stick

The ISO is a hybrid image: write it to the whole stick, not to a partition. A stick of 8 GB or more is enough. Everything on the stick is erased. Write only an image you have verified (Download & verify).

With install.sh (Linux)

install.sh downloads the latest published release. Until the first River release is tagged and published, there is nothing for it to fetch and this path cannot work — use By hand below with a locally built image. See Releases for what exists.

install.sh downloads and verifies the image first, then writes it:

curl -fsSL https://raw.githubusercontent.com/org-runink/river/main/install.sh | sh -s -- --write /dev/sdX

It refuses a device that is not a whole disk, is neither USB nor removable, is mounted, or reports no serial number. Before it writes, it shows the stick’s model, size and serial and asks you to type the serial, so a typo in /dev/sdX cannot erase the wrong disk. For a scripted run, pass the serial you checked with --yes-i-have-checked-serial=SERIAL.

The script never runs sudo. Run as a normal user, it verifies the image and the stick, then prints the one command that needs root, for you to run:

sudo dd if=./runink-river-<YYYYMMDD>-x86_64.iso of=/dev/sdX bs=4M conv=fsync oflag=direct status=progress

Add --dry-run to see what it would write without writing anything, and --out DIR when the image is in, or should go to, another directory. Every flag is described on Download & verify.

By hand (Linux)

Find the stick, check its size, model and serial, unmount anything mounted from it, then write the verified image:

lsblk -o NAME,SIZE,MODEL,SERIAL,TRAN,MOUNTPOINTS   # the stick shows TRAN=usb
sudo umount /dev/sdX1                              # for each mounted partition of the stick
sudo dd if=runink-river-<YYYYMMDD>-x86_64.iso of=/dev/sdX bs=4M conv=fsync oflag=direct status=progress
sync

/dev/sdX is the whole device (/dev/sdb), never a partition (/dev/sdb1).

Check the stick afterwards

dd reporting success is not the same as the stick holding the image. A failing or counterfeit stick accepts every write and returns different bytes on the next read, and conv=fsync cannot detect that. Read it back and compare:

sudo cmp -n $(stat -c %s runink-river-<YYYYMMDD>-x86_64.iso) \
     runink-river-<YYYYMMDD>-x86_64.iso /dev/sdX && echo "the stick matches the image"

cmp prints nothing and exits 0 when every byte matches; it names the first differing byte otherwise. The -n limit stops it at the image’s length, because the stick is larger than the image and everything past the end is expected to differ.

A stick that writes without error and fails this is the one that boots to a GRUB rescue prompt or a kernel panic much later, when the cause is no longer obvious.

From Windows or macOS

Any tool that writes a raw disk image byte for byte works. Pick “write an image as-is” (dd mode) if the tool asks, and verify the image before you write it.

Boot it

Plug the stick in, open your firmware’s boot menu (often F12, F11, F8 or Esc at power-on) and pick the USB stick’s UEFI entry. Turn Secure Boot off first: the image does not boot with Secure Boot on yet (Secure Boot).

The stick’s live system then opens the installer by itself: Install. It does not start? Troubleshooting.

Reuse the stick afterwards

The installer never offers the stick as a target and never saves the recovery key to it. To use the stick for files again, recreate a partition table and a filesystem on it with parted or gdisk (on the installed system) or any partitioning tool.