documentation/docs/alpine-desktop-setup/installation.md

# Installation

To install the Alpine Linux distribution on the system, the datasets of the system pool and the EFI partitions have to be mounted to the main system. 

First import and decrypt the system pool.

```
# zpool import -N -R /mnt tank
# zfs load-key tank
```

Mount the datasets in the system pool and decrypt the home dataset.

```
# mount tank/root/alpine /mnt -t zfs -o noatime
# zfs mount tank/home
# zfs mount tank/var
```

Mount the ESP.

```
# mkdir /mnt/esp
# mount /dev/disk/by-label/esp /mnt/esp -t vfat
```

Then install Alpine Linux.

```
# export BOOTLOADER=none
# setup-disk -m sys /mnt
```

To have a functional chroot into the system, bind the system process directories.

```
# for dir in dev proc sys run; do
> mount --rbind --make-rslave /$dir /mnt/$dir
> done
# chroot /mnt
```

The other setup scripts can be used to configure key aspects of the system. Besides that a few necessary services have to be activated.

```
# setup-hostname <hostname>
# setup-keymap us us-euro
# setup-timezone -i <area>/<subarea>
# setup-ntp openntpd
# rc-update add acpid default
# rc-update add seedrng boot
# rm -rf /var/tmp
# ln -s /tmp /var/tmp
# passwd root
```

> The root password does not really matter because it is going to be locked after a user has been created.

Set the `hwclock` to use `UTC` in `/etc/conf.d/hwclock` and disable writing the time to hardware. Running a NTP negates its usability.

```
clock="UTC"
clock_hctosys="NO"
clock_systohc="NO"
```

Configure the ESP raid array to mount.

```
# modprobe raid1
# echo raid1 >> /etc/modules-load.d/raid1.conf
# mdadm --detail --scan >> /etc/mdadm.conf
# rc-update add mdadm boot
# rc-update add mdadm-raid boot
```

Configure ZFS to mount.

```
rc-update add zfs-import sysinit
rc-update add zfs-mount sysinit
```

Edit `/etc/fstab` for correct mounts:

```
tank/root/alpine   /           zfs     rw,noatime,xattr,posixacl,casesensitive     0 1
/dev/md/esp        /esp        vfat    defaults,nodev,nosuid,noexec              0 2
tmpfs              /tmp        tmpfs   rw,nodev,nosuid,noexec,mode=1777          0 0
proc               /proc       proc    nodev,nosuid,noexec,hidepid=2             0 0
```

By default, Alpine Linux uses `mkinitfs` to create an initial ram filesystem.

```
# apk add secureboot-hook sbctl
```

Configure `/etc/mkinitfs/mkinitfs.conf` to disable it's hook:

```
# echo 'disable_trigger=yes' >> /etc/mkinitfs/mkinitfs.conf
```

The most important step is the creation of a UKI using `secureboot-hook` which also automatically signs them. Configure `/etc/kernel-hooks.d/secureboot.conf` for cmdline and secureboot. 

```
cmdline="rw root=ZFS=tank/root/alpine quiet splash"

signing_cert="/usr/share/secureboot/keys/db/db.pem"
signing_key="/usr/share/secureboot/keys/db/db.key"

output_dir="/esp/efi/linux"
output_name="alpine-linux-{flavor}.efi"
```

Use `sbctl` to create secureboot keys and sign them.

```
# sbctl create-keys
# sbctl enroll-keys
```

> Whilst enrolling the keys it might be necessary to add the `--microsoft` flag if you are unable to use custom keys.

Set the cache-file of the ZFS pool.

```
# zpool set cachefile=/etc/zfs/zpool.cache tank
```

Now to see if everything went successfully, run:

```
# apk fix kernel-hooks
```

and it should give no warnings if done properly. 

To install `gummiboot` as friendly bootloader:

```
# apk add gummiboot
# mkdir /esp/loader
# mkdir /esp/efi/boot
# cp /usr/lib/gummiboot/gummibootx64.efi /esp/efi/boot/bootx64.efi
```

Sign the bootloader with `sbctl`.

```
# sbctl sign -s /esp/efi/boot/bootx64.efi
```

> One may verify the signed files by running `sbctl verify`, in this case `ESP_PATH=/esp` should be defined to work properly.

`gummiboot` can be configured with the file `/esp/loader/loader.conf` with which the timeout and the default OS can be specified.

```
default alpine-linux-lts.efi
timeout 5
editor no
```

> Here, there should be lines explaining the setup of automatic decryption with TPM using Clevis. Which is still in development...

```
# clevis encrypt tpm2 '{}' << ''
```

Before finishing the installation `networkmanager` will be installed for networking. Also install `networkmanager-wifi` and `wpa_supplicant` for Wi-Fi functionality.

```
# apk add networkmanager networkmanager-wifi wpa_supplicant
# setup-devd udev
# rc-update add networkmanager default
```

Wi-Fi will not yet work. For Wi-Fi configuration see the network section. 

> If internet does not work after reboot create the config file as described in the network section and restart the service.

Now exit the chroot and you should be able to reboot into a working Alpine system.

```
# exit
# umount -lf /mnt
# zpool export tank
# reboot
```