# How to Install and Run Alpine Linux with Cloud Hypervisor

This guide walks you through installing Alpine Linux into a QCOW2 disk image using QEMU, and then running that image with [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor). It includes all the steps you’ll need, from creating the disk, performing the OS install, preparing kernel/initramfs, and finally running the VM with Cloud Hypervisor.

---

## **Goal**

- **Install Alpine Linux into a disk image using QEMU**
- **Extract the installed kernel and initramfs from the disk**
- **Boot the VM with Cloud Hypervisor, using direct kernel/initramfs boot**

---

## **Prerequisites**

- Ubuntu (or Debian-based) host
- `sudo` privileges

---

## **Instructions**

### 1. **Install required tools**

```sh
sudo apt update
sudo apt install -y qemu-utils wget curl qemu-system-x86 libguestfs-tools
```

### 2. **Download Cloud Hypervisor binary**

```sh
wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v47.0/cloud-hypervisor-static
chmod +x cloud-hypervisor-static
```

### 3. **Download Alpine Linux ISO**

We will download the `alpine-virt` ISO, which is similar to the standard ISO but has a slimmed down kernel and is optimized for virtual systems.
```sh
wget https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/x86_64/alpine-virt-3.22.1-x86_64.iso
```

### 4. **Create a blank disk image**

The command below will create a blank disk image called `alpine-vm.qcow2` with a size of 2GB. 
```sh
qemu-img create -f qcow2 alpine-vm.qcow2 2G
```

### 5. **Install Alpine into the disk image**

> **NOTE:** _Cloud Hypervisor does not emulate legacy BIOS/UEFI, so we use QEMU for the initial install._
```sh
qemu-system-x86_64 -m 1024M \
    -cdrom alpine-standard-3.22.1-x86_64.iso \
    -drive file=alpine-vm.qcow2,format=qcow2 \
    -boot d \
    -net nic -net user,hostfwd=tcp::2222-:22 \
    -nographic
```
- **Inside the VM:**
    - Log in as `root` (no password by default).
    - Run `setup-alpine` and complete the installation steps.

### 6. **(Optional): Boot into the installed Alpine system with QEMU**

1. Boot into VM:

```sh
qemu-system-x86_64 \
    -m 1024M \
    -drive file=alpine-vm.qcow2,format=qcow2 \
    -net nic -net user,hostfwd=tcp::2222-:22 \
    -nographic
```

2. Install `curl` and `k3s` on the VM:

```sh
apk update
apk add curl
curl -sfL https://get.k3s.io | sh -
```

### 7. **Enable serial console in Alpine VM**

Edit the `/etc/update-extlinux.conf` in the VM and set:

```sh
serial_port=0
```

This ensures the kernel output is available on the serial port, which we use later when launching the VM with Cloud Hypervisor (using the `--serial tty` command line argument).


### 8. **Extract kernel, initramfs and kernel parameters from the installed disk**
> **NOTE**: You only need to mount the QCOW2 disk once to get all necessary files and information.

1. Mount the disk using guestmount

```sh
sudo guestmount -a alpine-vm.qcow2 -i /mnt
```

2. Copy the kernel and initramfs:

```sh
cp /mnt/boot/vmlinuz-lts ./vmlinuz-lts
cp /mnt/boot/initramfs-lts ./initramfs-lts
```

3. Get the kernel command line parameters and the root UUID:

```sh
cat /mnt/boot/extlinux.conf
```

Look for the `APPEND` line under your boot label (e.g. `LABEL lts`). Example:

```maxima
LABEL lts
  MENU DEFAULT
  MENU LABEL Linux lts
  LINUX vmlinuz-lts
  INITRD initramfs-lts
  APPEND root=UUID=8b578951-b524-42b9-a757-67fa90b56ec8 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4
```

- Copy everything from `root=UUID=...` to the end of the line (after `APPEND`).
- You will use this as your kernel command line in Cloud Hypervisor

4. Unmount the disk

```sh
guestunmount /mnt
```

### 9. Boot Alpine VM with Cloud Hypervisor

Use the kernel and initramfs you extracted, and set the full kernel command line (adjust UUID and modules as needed):

```sh
./cloud-hypervisor-static \
  --kernel ./vmlinuz-lts \
  --initramfs ./initramfs-lts \
  --disk path=alpine-vm.qcow2 \
  --cpus boot=2 \
  --memory size=1024M \
  --net "tap=,mac=,ip=192.168.100.2,mask=255.255.255.0" \
  --serial tty \
  --cmdline "console=ttyS0 root=UUID=8b578951-b524-42b9-a757-67fa90b56ec8 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4" \
  --console off
```

- **Replace the UUID and modules with your values from step 8.**