Installing Alpine Linux on a Raspberry Pi

Alpine is a fast, lightweight Linux distribution that's easy to install and ideal for the Raspberry Pi. It's designed to be run on minimal hardware so it comes with a barebones setup and limited number of packages which makes it a great choice for those who want to know exactly what applications are running while minimising disk space and processor usage.

Alpine Concepts

Due to Alpine being a barebones Linux distribution it can be a bit trickier to get things set up than say Ubuntu or Raspbian. You will find that even some basic packages you're familiar with won't be available from a standard installation, but everything is deceptively easy to install and when you're finished you're guaranteed to only have installed only the tools you need rather than lots of unnecessary packages and background services.

Working with Alpine Linux is definitely worth the effort as you'll learn a huge amount about Linux and understand how to install applications that we usually take for granted in more widely used distributions.

Installation

These installation instructions have been designed for absolute beginners to Raspberry Pi, Alpine and Linux in general. If you have any issues while following them

Choose the correct Alpine version for your Raspberry Pi model
Formatting the SD card
Copy Alpine to the SD card
(Optional) Add an answers file
Plug the SD card in
Plug all the cables in
Log in for the first time
Run setup or if you created an answers file run setup with an answers file instead
(Optional) Additional setup for user accounts, SSH, Firewall and Docker
(Important) Learn about committing changes

After you've followed these steps you will have a working Alpine installation. Now you can follow the instructions on Getting started with Alpine. However, if you got stuck or had unexpected results then please check out the troubleshooting section.

And if you're still stuck after all that please feel free to open an issue or send me a Tweet and I'll do my best to help.

Choosing the correct Alpine version

There are currently 3 different versions of Alpine for the Raspberry Pi on the Alpine downloads page; armhf, aarch64 and armv7 and choosing the right one for your model can be very confusing. There isn't a great deal of simple information to tell you which version you need based on the architecture of the processor on your Pi.

The following table shows the Raspberry Pi versions I've tried these instructions on so far. I'll update with more as I test them:

Raspberry Pi Model	armhf	armv7
A+
B+	✓	✗
2B		✓
3B
3A+
3B+		✓
4B
Zero
Zero W
Zero WH

Formatting the SD card

On Windows

For the purposes of this guide I'll be using the FAT32 partition scheme. As a user who primarily uses Windows I've found that the easiest way to get started with Alpine is by formatting the entire SD card using FAT32.

There are other partition schemes that may be more suitable for a Linux environment, such as ext4, but they do require a little more work to get up and running, they'll usually require a 3rd party partitioning tool as Windows does not natively support most Linux file system formats. If you're choosing an alternative partition scheme you've probably got enough knowledge to know how to do it anyway.

Warning: Please be careful with the following instructions. You can potentially lose data if you are not careful. I can't be held responsible for any loss of data caused by following these instructions.

Plug the SD card into your computer and ignore any warnings Windows may pop up with. It may offer to format the disk for you, we're going to do it ourselves so just close or cancel the window.
Press the Start or Windows button on your taskbar then type diskmgmt and enter. The Windows Disk Management application will open.
Locate your SD card on the listing
If the SD card has any partitions already first make sure you are absolutely sure you want to lose all data on the disk. If you do then right click them and select Delete Volume until there are none left.
Right click the empty drive and create a primary partition of 512MB* formatted as FAT32, then assign it a drive letter.

Don't worry that we're only creating a partition of 512MB. The rest of the space on the disk will become available later after running the Alpine setup script.

Important: Make sure all partitions on your disk are removed prior to creating the new partition otherwise Alpine may have issues booting.

Copy Alpine to the SD card

Alpine is great because you don't necessarily need to use a dedicated application like Etcher to put it on the SD card. You can just copy the files in Windows Explorer.

Extract the file (verify checksums)

Add an Answers File

When you run the setup-alpine script on your new Raspberry Pi Alpine installation you have the option of providing an answers file. This file will automatically answer all of the questions for you regarding keyboard layout, timezone, network devices etc. It's a good way to save time when setting up new Alpine installations as you won't have to manually answer all the setup questions.

You don't have to add an answers file for setup to run. If you don't provide one it will run in interactive mode asking you questions on each step. An answers file just removes this step from setup and makes it easier if you're setting up more than one Pi to share the same settings.

You'll need to download a copy of this sample answers file and replace all the values for the following <KEYBOARDLAYOUT>, <KEYBOARDVARIANT>, <HOSTNAME>, <IP>, <NETMASK>, <GATEWAY> and <DNS>.

Once this is done you can copy it to the root of the SD card alongside all the other Alpine installation files.

Plug in the SD Card

Safely eject the SD card from your computer, ensuring that all the files have finished copying and it is not being accessed.

Ensure the Raspberry Pi is turned off before attempting to plug in the SD card. As it doesn't have an on/off switch you'll need to make sure it's turned off at the socket or the power cable is unplugged. Once it is off turn it upside down and along one of the short edges you'll notice an SD card slot where you can plug in the card.

Plugging an SD card in while the Raspberry Pi is working probably won't do any harm, but the system won't boot properly unless the SD card is present when the power is turned on.

Important note: If you used a USB stick to plug the SD card into your PC you'll need to take that off. The Raspberry Pi will only boot from the SD card slot, it won't boot from a USB port.

Plug the Cables In

Plug all your cables into the Raspberry Pi (making sure the power cable is last)

Log In for the First Time

The default username for a new Alpine installation is root and the password is empty. This should get you access to the terminal where you'll be able to make whatever changes you want.

I highly recommend that you add a strong password to the root account immediately to stop unauthorised access to your Raspberry Pi. You can do this by using the command:

sudo passwd root

Once you've set the password you'll need to use it when logging in with the root account. It's also best practice with Linux to not use the root account unless you absolutely have to, instead using a secondary account for day-to-day access and only using root when it's absolutely required.

Run Setup

Alpine on the Raspberry Pi comes with a setup script which really helps to automate setting up the applications and features for new users.

If you run setup-alpine you'll enter an interactive setup questionaire that will help you configure everything. Some of the questions might be a bit confusing for those users who are new to Linux, networking and computers in general so here are some sample answers that can get you up and running quickly (however if you created an answer file previously then skip this step):

If you get anything wrong you can hit CTRL+C at the same time to cancel setup and start again. Just run setup again using the command above.

When choosing a mirror you can just press f this test the speed to all of the mirrors and choose the fastest, or r for a random mirror.

Run Setup with Answers File

If you created an answers file and copied it onto the SD card you should be able to provide it as an input parameter to the setup script which will then use those values to automate the setup script. To run the setup script with an answers file run the following command:

setup-alpine -f /media/mmcblk0p1/<ANSWERFILE>

Replacing the <ANSWERFILE> part with the name of the file.

Additional Setup

There are some post-install setup scripts which will set up a number of things for you, such as:

Useful tools such as sudo, curl and nano
Standard user for logging in
Firewall installed and setup to block all traffic apart from SSH
SSH
Docker

You can run these scripts individually or all together. To set them all up run the following commands:

apk add curl curl -o setup.sh -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/garrym/raspberry-pi-alpine/master/setup.sh chmod +x setup.sh ./setup.sh

This will automatically run everything in order. However if you wanted to run individual scripts, just use the same code above and replace setup.sh with setup-packages.sh, setup-user.sh, setup-firewall.sh, setup-ssh.sh or setup-docker.sh instead.

Important: Committing

This Alpine installation runs in sys mode which is a read-only file system. This means any applications you install, configuration changes you make or files you write will not be saved after restarting unless you commit them using the command:

lbu commit -d

It's important to remember to do this when working with Alpine. It can be very frustrating when you forget to commit and all your changes disappear after a restart. You can commit as regularly as you want and it won't cause any problems. Commit early, commit often.

I prefer using sys mode with Alpine as it makes your device feel more like an appliance with immutable data that you can guarantee will be in the same state even after restarting, however it is possible to have a writable filesystem by doing the classic Alpine install. For more information on this check out the Alpine Wiki on classic install vs sys mode.

Getting Started

Getting around Alpine

Access the SD card by cd /media/mmcblk0p1/

Alpine Package Manager

Alpine uses apk as it's package manager. This is what you can use to install and remove software. For more information check out the (Alpine Linux package management page)[https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management] on the wiki.

Troubleshooting

Blank screen when booting the Raspberry Pi

This typically happens when either the SD card isn't plugged in correctly or the Raspberry Pi can't recognise the boot sequence of the SD card.

First make sure your SD card is seated correctly and restart it by unplugging the USB power cable and plugging it back in.

If the issue still persists try re-following the instructions for formatting the SD card, making sure that all existing partitions have been removed and the card is formatted using the FAT32 partition scheme.

Monitor not recognising the Raspberry Pi

The Raspberry Pi has some built in configuration that allows it to run in headless mode and ignore the HDMI port to save power. If the Raspberry Pi is booted without a HDMI cable connected then it will not recognise the monitor. There are some workarounds for this and you can alter the config.txt to permanently enable the HDMI port.

Try to restart the Raspberry Pi with the HDMI cable connected.

garrym / raspberry-pi-alpine