{
	"title": "Alpine Linux installation",
	"subtitle": "Installation guide for the Alpine Linux operating system"
}

#### Introduction

[Alpine Linux](https://alpinelinux.org/) is a very lightweight and simple Linux
distribution. It is especially well suited to run servers. This article should
provide a reference how to install it inside a
[QEMU](https://www.qemu.org/)-based virtual machine.

It has to be noted that the installation mode will be the [diskless
mode](https://wiki.alpinelinux.org/wiki/Installation#Diskless_Mode) which
erases all changes on a reboot if they were not saved by the
[lbu](https://wiki.alpinelinux.org/wiki/Alpine_local_backup) utility.

#### Create virtual machine image file

The first step to setup the virtual Alpine machine is to create a `vm.qcow2`
file which will be used as the disk for the final virtual machine:

```
qemu-img create -f qcow2 vm.qcow2 30G
```

It has to be noted that the size is set to 30 gigabytes which is what the VM
will see. Independent of that virtual size the `vm.qcow2` file will use only as
much disk space as required on the host system so that the file is actually way
smaller than 30 GB.

#### Start and setup temporary Alpine system

An Alpine Linux image file is required for the first run of the virtual
machine. They can be obtained on the [Alpine Linux download
page](https://alpinelinux.org/downloads/).

For this article the image `alpine-standard-3.18.4-x86_64.iso` was selected. To
start QEMU with the created `vm.qcow2` disk connected and the Alpine image file
inserted the following command is used:

```
qemu-system-x86_64 \
    -enable-kvm \
    -m 4G \
    -nic user,model=virtio \
    -drive file=vm.qcow2,media=disk,if=virtio \
    -smp cpus=4 \
    -display sdl \
    -cdrom alpine-standard-3.18.4-x86_64.iso
```

After booting this the live system has to be prepared. For this purpose one can
log in with the username `root` and use the following setup script:

```
setup-alpine
```

This interactive program will configure the system. A quite minimal
configuration should be preferred. The defaults are usually sufficient. Disks
and SSH servers should not be configured.

Future versions of this article should provide a so called "answers file" for
`setup-alpine` so that the script can run without user interaction.

#### Make disk bootable

Since the created virtual disk `vm.qcow2` is empty and thus cannot be used
without the Alpine image file the next step is to make it independently
bootable.

Since `lsblk` is not included in the default Alpine image file the command `ls
-l /dev/block` has to be used to list all block devices which include the
created virtual disk.

```
ls -l /dev/block
```

The output should contain a symbolic link to a file like `/dev/vda` which
corresponds to the created `vm.qcow2` file on the host system.

The next step is to create a partition table and one partition on that disk to
store the operating system. The interactive program `fdisk` is used for that
purpose. The exact inputs are noted down below. An empty line requires to
accept the default by hitting only 'Enter':

```
fdisk /dev/vda
o
n
p
1
2048

t
0c
a
1
p
w
```

This will create a new DOS partition table, create one primary partition which
takes the whole size of the disk, set the type of this partition and make it
bootable. Finally the result is printed with `p` and the changes are written to
disk with `w`. The process can be aborted by hitting `q` before `w` is used.
`m` will print details about all available options.

After partitioning the only created primary partition has to be formatted. This
can be done with the following command:

```
mkdosfs /dev/vda1
```

To allow mounting DOS filesystems and prevent errors on the next command the
`vfat` kernel module has to be loaded with `modprobe`:

```
modprobe vfat
```

The final command to make `vm.qcow2` bootable is

```
setup-bootable /media/cdrom /dev/vda1
```

It will copy the contents of the Alpine live image mounted at
`/media/cdrom` to the just formatted DOS partition `/dev/vda1` and installs the
syslinux bootloader to the disk `/dev/vda`.

The temporary Alpine system can be powered off with `poweroff`.

#### Configure final system

Booting the final system the first time works like with the
`qemu-system-x86_64` command for the temporary system except that the `-cdrom`
option has to be ommitted. This is possible since `vm.qcow2` is now
independently bootable.

The final system can be configured like the temporary one:

```
setup-alpine
```

By default only the `main` package repository is enabled. If it is required to
also install packages from the `community` repository it has to be enabled in
the related configuration file:

```
vi /etc/apk/repositories
```

An upgrade to the latest package revisions on the Alpine Linux package servers
is a good idea at that point:

```
apk upgrade -a
```

Finally the changes have to be changed with the `lbu` tool to make it
persistent after reboots:

```
lbu commit -d
```

#### Install a desktop system

The optional installation of a graphical desktop is also well supported by a
setup script:

```
setup-desktop
```

Currently the GNOME desktop, KDE Plasma and Xfce are supported. Xfce worked
best so far.

Finally the installation of the desktop environment has to be committed too:

```
lbu commit -d
```

The last step can be ommitted to remove the desktop environment cleanly after a
reboot.