Features

This is an installer for Alpine linux with ZFS as root filesystem, and ZFSBootMenu to boot into different environments.

Since installing Alpine with ZFS and ZfsBootmenu needs a whole tutorial with many steps, we've created this easy installer.

• Fastest and easiest way to install Alpine on ZFS
• Uses the excellent ZFS filesystem.
• ZFSBootMenu as bootloader, which allows you to rollback in case of failed upgrades.
• After installing it can boot in both BIOS mode and UEFI mode.
• Perfect for running docker.
• Also easy to install at VPS providers that do not provide an Alpine installer.
• Install time is about 1 minute.

Why Alpine Linux?

Alpine is one of the best and cleanest Linux distros out there, for running Docker and various other stuff. Packages like the Linux kernel, ZFS support and Docker are not only very up to date, but also very stable.

It's super small, fast and simple. It's not the most versatile distribution, but what it does, it does very well.

Also upgrading to newer releases is quick and painless, in contrast to other distro's. And since we use snapshots before upgrading, it's easy to roll back should there be a problem.

For this reason all our boxes run Alpine and just auto-upgrade and reboot every week without problems.

Installing

Installation by just writing the official image to the disk is the easiest way:

• Boot any Linux distro via CD, USB. Or use a rescue-boot if you use some kind of VPS hosting provider. (example screenshot below)
• It doesn't matter if this linux distro has UEFI or legacy boot, the image contains both and should always boot. (you can even switch between uefi and legacy afterwards)
• Download the imager:

# wget https://boot.datux.nl/image

NOTE: This is just a redirect to https://raw.githubusercontent.com/psy0rz/alpinebox/master/install/installimage.sh

• Start the imager and specify your harddisk:

# bash image /dev/sda

This should download and reboot, and you're basically done :)

If you have trouble installing. see VPS provider tips

Login

There is no root-password for console logins. However, for ssh you will need to add your keys.

Growing the disk

Since it's an image, you will need to grow the partition and zfs disk:

Just run grow-disks script in /root/alpinebox, and it should be handled automatically, without needing a reboot.

Do this as soon as possible, since it's a somewhat risky operation

Adding a disk

To add a disk to the zpool as a mirror, just run the add-disk script in /root/alpinebox

This will also make sure that the disk has the correct partitioning, MBR/UEFI and ZfsBootmenu stuff, so that if the first disk completely fails, you can still boot from this one.

Make sure you remove any non-ONLINE disks from the pool first.

Backups

To make backups via ZFS replication, check out my other project: https://pypi.org/project/zfs-autobackup/

Safe updates

Now everytime you need to do a bunch of Alpine upgrades, just run something like: zfs snapshot rpool/ROOT@upgrades1

If the upgrade fails you can rollback via the ZfsBootmenu.

Installing docker or portainer

After installing alpinebox, go to /root/alpinebox.

Here you will find various install scripts.

To install docker, just run ./install-docker

If you also want portainer, run ./install-portainer instead.

This will give you further instructions on what to do after it's done.

Installing firewall

Go to /root/alpinebox and run ./install-firewall

This will install a minimal firewall that only allows ssh from trusted IP addresses (via ipsets in /etc/ipset.d/).

This will not interfere with docker. The script will provide you with more info after running it.

VPS provider tips:

Here are some specific VPS provider tips on how to get into an environment to start the installer:

Hetzner cloud:

If you have a hetzner VM.

Via the Hetzner console request a Rescue boot. See this screenshot.

Hetzner robot:

If you have a hetzner dedicated server.

Method 1 (cli rescue only):

• Start the server in rescue mode
• Use the default imaging install method shown above, dont reboot.
• Now we need to set the root password or add ssh keys:
• zpool import -R /mnt rpool (first time this will auto install zfs tools)
• chroot /mnt
• Setup root password or add ssh keys.
• Exit and reboot

Method 2 (hetzner vkvm):

This starts your harddisks as a qemu VM, with vnc access. Much nicer for testing/fixing stuff.

• Start the server in vkvm mode.
• Login to the ssh rescue environment on port 47772 (login as root and with the password hetzner gave you in their control panel)
• Stop vkvm: systemctl stop vkvm-startup so your harddisk is accessible.
• Use the default imaging install method shown above, dont reboot.
• Start vkvm: systemctl start vkvm-startup
• Server should boot, and be accessible via webinterface at https://x.x.x.x:47773/ (hetzners control panel tells you this)
• Login and add ssh keys or set root pass.
• Now you can reboot the rescue shell and make the server actually boot by itself.

UEFI boot problems in vkvm

Sometimes it seems to get stuck in a UEFI boot loop. When this is the case, simply disable it like this:

• Edit /opt/vkvm/startqemu
• Remove -drive if=pflash,format=raw,file=/usr/share/OVMF/OVMF_CODE.fd
• systemctl restart vkvm-startup

This should boot it in bios-mode without any problems.

TransIP

Open the console screen in popup-mode and choose to boot linux in Rescue mode. See this screenshot.

Once you've entered the rescue environment, you can use the Alpinebox installer mentioned above.

Requires a power cycle of the VM, not just a reboot, to get it working.

More info

Based on this excellent tutorial: https://docs.zfsbootmenu.org/en/v2.3.x/guides/alpine/uefi.html