Alpine Linux: Overview, Installation and Setup

Overview

How to use Alpine Linux with my applications and capabilities, like installing a desktop?

Typically, Alpine Linux is used as a base Linux distro for containers (eg. Dockerfiles) due to its small footprint and low resource consumption.

However, since v3.20+, the base image has grown to nearly 1GB (it no longer fits on a 700MB CD). That said, it’s still relatively a very small ISO and not every package contained within it needs installed on every system.

Since Alpine Linux handles running individual services and tasks extremely well, it is actually a great solution for separation of concerns in software development. With each container or VM, you can configure specific services or tasks “atomically”, and monitor the logging and output from each instance. You can actually test that your Alpine Docker image or environment works as expected before deployment, and save time (Alpine Linux SO FAST) and often disk space, CPU and RAM resources too by using Alpine as a Guest VM in your hypervisor(s).

Always use at least 2 vCPU cores, as I recommend with nearly all Operating Systems. The performance difference between 1 and 2 vCPUs is dramatic. For using a desktop environment like Gnome or KDE/Plasma, I recommend at least 4GB of RAM, but for lighter weight DE’s a minimum of 2GB of RAM can work (until you have more than 20 browser tabs open…). If you don’t plan on using a Desktop Environment (DE) then you can actually get by with as low as 256MB of RAM. Yes, you read that right: 256 Megabytes is one-quarter of a Gigabyte of RAM, which is enough to run Alpine Linux v3.21+ (for something like a DNS Server).

Setting up Alpine Linux as a Guest VM or Bare Metal operating system is extremely fast and simple. Use the ISO (Hypervisors) or “burn” to a USB with your favorite method (eg. Etcher), and configure your BIOS/UEFI to boot from USB (or however you want to do it). The setup process takes only a few minutes and once you get the hang of it, it’s an absolute breeze.

List of Best Uses for Services for an Alpine Linux Guest OS VM

Alpine Linux is great for a number of things. It’s fun to work with as it performs extremely well as an operating system because of its small footprint and low resource use. But overloading Alpine Linux with too many CPU or RAM intensive tasks can bog the system down severely. For example, if you have 2 vCPU core and 4GB RAM in an Alpine VM and then install the xfce desktop and attempt to open over 50 tabs in a browser window, you’re going to have a bad time. But under 20 tabs with a chromium-based browser is realistic, assuming you aren’t running too many other heavily used services in the background.

Keeping in mind the realities of using Alpine as an atomic, single purpose “node” of your network as best practices, there are a few other opportunities that you can find to combine a few resources. As long as two or three different services are not using a lot of CPU or RAM consistently, but in “schedulable bursts”. Such is the case with Development/Staging/Test environment databases, NFS Servers, DNS Servers, and any sort of build tools for CICD pipelines and container images. So there are opportunities for more complete resource utilization of a single VM, particularly in a home lab of on-premises non-production environment. For production environments, this will NOT be recommended, as dedicated production resources are typically security hardened and have limited access, and containers or VMs tend to be more atomic (isolated and separated), by design.

As with any low-resource Linux of BSD OS distribution, there are some limits to available tools, features and functionality. Alpine has many of these issues, too. Such as while there are many available desktop environments for Alpine Linux via the setup-desktop script, or manual installation, there are often issues with differences in Hypervisor of container management platforms that vary between them. For example, with Xen-based hypervisors, the desktop environments rely on “*dm” (Display Managers) packages that handle power related functions like sleep and suspend. Xen-based Hypervisors (such as libvirt, XCP-ng, QubesOS, Oracle VM Server and others) are known for not being able to handle the transitions to and from the “suspend state” properly, which typically results in a crashed/frozen operation that requires a reboot. This can be particular difficult to deal with in more robust desktop environments designed for (and tested against) bare metal or other Hypervisor paradigms, such as Gnome. Since many Linux applications rely on Gnome, the almost-but-not-quite polish on Gnome DE for Alpine is not recommended, but YMMV if you are able to disable suspend and other buggy features.

Lastly, there is sometimes a lack of Linux Distribution support for specific tools across all Linux distributions. For example, Docker Desktop, which primarily works on Debian-based distributions, and typically limited to RHEL and Fedora for RPM-based Linux Distros. In such a case with Alpine Linux, there are alternative products that can manage containers, such as podman and podman-desktop (via Flatpak/Flathub), but with limited supporting features by comparison to Docker offerings. But Portainer does not offer the same level of interaction with containers from the perspective of a Developer. Though, still, it may be that the Developer already has a functional laptop or PC with a more resource-intensive operating system that s/he can use to create the container images with and upload them to a container registry. In such a case, Portainer installed on Alpine could be useful for testing said images

• Virtualization / Containerization
  • Docker (Engine)
    • Docker Compose
  • Podman (Engine)
    • Podman Desktop works with xfce via Flatpak+Flathub
  • Kubernetes (Control Plane or Worker nodes)
• Network Services
  • DNS Server (CoreDNS, BIND9, pi-hole [Alpine variant], Unbound, etc)
  • NFS Server (Network File Storage server works well)
  • Load Balancer (Network, Application or “Classic”)
• Web Services
  • Web Server (nginx, Apache, lighttpd)
• Development Services
• Security
• Databases
  • PostgreSQL – Single Instance Only (multiple version installation not recommend…)
  • MariaDB – We will use non-Oracle DBs, as the threat to license changes and heavy resource consumption/requirements do not exist with MariaDB like with MySQL and they are 99% identical in feature offerings

---

Alpine Linux Installation

Quick Install Hints for Your First Time Installing Alpine as an OS (and not for use with a container)

• use the username root at the initial install login prompt
• At the initial terminal prompt, type: setup-alpine
• Don’t know which install-to-disk type to choose? Pick sys for the easiest choice to get up and running
• Once all the prompts are complete (only about a dozen or so), reboot your system and your done
• *Don’t forget to remove the USB / “eject” the ISO or you may reboot back into the installer again, even though you already finished the install

With the above tips, even as an Alpine newbie, you could have a working Alpine system in about 5 minutes, especially if you have DHCP on the network.

You can use the setup-desktop script to choose a Desktop Environment (DE) GUI. If you need one, I recommend xfce for Alpine – it works fairly well with as low as 2GB of RAM. Depending on the Desktop Environment of your choice, you will likely need to do some “touch up” after the setup-desktop script completes.

Before you attempt to install a DE, edit the file /etc/apk/repostiories to include the community repository (uncomment the line with the url that ends in “/v3.xx/community” and try installing from there, first. If that doesn’t work for your chosen DE, you can try adding the /edge/community repo, later)

I’ve tested a few different desktops with Alpine, but I always go back to xfce as its the best of both worlds – a complete desktop with tray, menus, taskbar, launcher and plugin integrations, while maintaining performance of the overall systems (Its not flashy, but its fast and useful).

Once you have your desktop installed, you may find that you are limited in the available packages provided by the main of apk. See here for my notes and a re-useable script for installing and/or repairing xfce on Alpine Linux.

In Q4 of 2024, the latest release for Linux Alpine was v3.20.3

Link to Alpine Linux APK packages

Review the list to see if the package you want is present. If not, there are other possible options to get the application you want. We will dive deeper into this later.

---

Enable the Alpine Linux community, edge and testing repos

So you want to use the new hotness that is Alpine Linux, but your desired package is still stuck in the /edge/{main,community,testing} repos? There are a few ways you can handle this… but keep in mind that edge repositories are NOT considered “production ready” and are often riddled with weird issues and bugs that haven’t been worked out yet. In other words, if your specific package doesn’t work “out of the box”, it might require you to make some very challenging edits to configurations to get things working. Are you ready for that? If not, then I recommend sticking to main and community repo packages, as even those aren’t always prefect, oftentimes the troubleshooting is much smoother and easier to work out.

The simplest way to enable (and therefore install) Alpine “edge” is to disable the “versioned main and community repos”.

Enable the edge, edgecommunity, and edgetesting repos by text-editing the file /etc/apk/repositories with the following contents:

IMPORTANT NOTE: Once you “upgrade” to using edge repositories, you may find it difficult to downgrade Alpine Linux from edge, edgecommunity and edgetesting back to main and community. Depending on the method of install and your configuration, there still might be a way, though.

How to Downgrade Alpine Linux from edge, edgecommunity and edgetesting Back to main and community

It is recommended that you first check that the apk packages that you have installed are actually existent in the repositories you want to downgrade too. Also sometimes important is the version of the apk package that may require a different format for the configuration files that you have created for it. So many possibilities here that it is impossible to mention all caveats, but hopefully you get the idea. For example, nginx versions vary between repositories. occasionally, nginx makes changes to its default configuration between versions (and also between distros…). Be aware of this.

To re-enable the non-edge repositories, edit /etc/apk/repositories like so (note that we have enabled community, which is NOT default):

In most cases, however, you will likely be fine to up and downgrade at will. Make sure you never do something like this in a production environment, though. Ever. You should only be debugging and testing your containers or Guest VMs with Alpine to determine how they will behave upon deployment.

Here is the best solution I have found to handle these cases for downgrading apk packages back to main and/or community repos for your Alpine version:

• Edit /etc/apk/repositories and comment the lines for the edge repos you want to disable, and uncomment/rewrite the lines with the URLs for main and community, then save the file edits.
• Execute doas apk upgrade -Ua --interactive
  • https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10705#note_109241
• It may be a good idea to reboot, if possible. If not, then hopefully you know the services that you should restart for your specific use case.
  • Example: doas rc-service dbus restart && doas rc-service xe-guest-utilities restart

---

A More Sophisticated Approach to Handling APK edge Repositories and Targeting Specific Packages

(Try saying that 5 times fast…)

There are a number of flexible options that apk provides for its users to install packages to meet specific needs. But there is added complexity involved, which could come at a high cost of time and unforeseeable surprises. Such as, if the package in an edge repository gets updated and breaks on your specific hardware configuration or hypervisor platform.

That said, apk (and Alpine itself) are still relatively “new” and also unique to the Linux distro mix, so as in 2024, there are a multitude of packages in the edge repositories that are actually working “out of the box” whereas perhaps the main and community repo packages are not.

Such is currently the case with xrdp and xorgxrpd (as of Q4 2024). The xrdp and xorgxrdp packages from community do not work for remotely connecting to an Alpine Linux instance, but if you use those from the edge community repository, they work very well. The trouble is, there are also other packages within the edge community repository that seem to cause issues with xfce (at this moment in time – Q4 2024).

So how can we use only the xrdp and xorgxrdp packages from edge community, but not pull them ALL in and cause potential issues? Let me show you:

To enable the edge repositories WITHOUT having all the existing (and hopefully working) packages pre-emptively upgrades to untested or semi-functional versions, edit /etc/apk/repositories like so:

With this configuration above, we can selectively choose which newer packages in the edge repositories that we want, without bringing everything else from the same repository with it. Here’s how:

doas apk add xrdp@edgecommunity xorgxrdp@edgecommunity

Now note that while this DOES work to get xRDP working in Alpine v3.20.3, there are some serious caveats to this approach… For example, once you use the @edgecommunity “tag” in the /etc/apk/repositories file configuration, the apk package manager will be looking to track those packages that you used with

doas apk add xrpd@edgecommunity xorgxrdp@edgecommunity

… Forever… meaning you can NOT change the @tagname in the /etc/apk/repositories file to something else, later on. This will break what apk calls its “world” configuration.

Do you see how that could get messy?

If you remove or change the @tagname from your /etc/apk/repositories and are then try to do anything with:

apk update ...

-or-

apk upgrade ...

you will then experience WARNINGs and ERRORs, like:

WARNING: The repository tag for world dependency ‘xorgxrdp@missingtagname’ does not exist
ERROR: Not committing changes due to missing repository tags…

But there is a fairly simple fix, if this is your situation. (No, it is NOT a good idea to use the –force-broken-world option).

You can simply edit the /etc/apk/world file and change the “@tags” that you deleted to the new names you have given the tags, or remove the tags in the list completely to use the “most current version your repository configuration will allow” – such as, the versions for packages are higher in the edge repositories than they are in the main or community repositories. But if you do not have the edge repositories actively configured, then you will get the most recent packages based on the repositories that you DO have configured.

Make sense? It is a bit confusing, This is considered “Advanced Usage” by the Alpine Linux Handbook for Alpine Package Keeper (APK). But I think you are getting it…

A true “test” for your efforts, is the magic that is in this particular apk update command:

doas apk upgrade -Ua --interactive

This command with upgrade the apk packages on your system by performing an update cache operation (-U), reset all packages to version available from your currently configured repositories in /etc/apk/repositories and then ask confirmation before performing certain operations (–interactive).

This effectively solves issues where you may have used packages from the edge repositories, and later changed your configuration back to using only main and community, but are still left with a “mix” of already installed packages from repositories you no longer want to use. And also important to mention, using the --interactive parameter provides the user an opportunity to “say no” if there is a change to a package version (upgrade/downgrade) that is not desirable.

So now, if you want to take things up another notch with Alpine Linux and apk, then I recommend this section (or really, the whole page has fantastic info on the cool tricks you can do with apk): https://wiki.alpinelinux.org/wiki/Alpine_Package_Keeper

Since I used the “@tagging” for the xrdp and xorgxrdp package installation and determined that the newer packages work, but the old one’s do not, I might make an assumption that in the next package version release, things may break. It’s very likely that in previous versions of Alpine Linux, the original packages from the community repos DID work, but something else “broke it” in a later release (regression bugs…) – so now, let’s explore how to determine which version of xrdp and xorgxrdp I have installed and working, and how to hold those packages at those versions, so I don’t get surprised by a loss of xRDP functionality during an update that might also contain valuable security patches.

doas apk policy xrdp

The above command shows me which versions of the package I have available through my /etc/apk/repositories configuration, and you can also identify which version in the list is currently installed (and also tagged).

0.9.24-r0: … v3.20/community
0.10.1-r0: … edge/community (installed)

So, in my current situation, as an Alpine Linux v3.20 user that needs this versions of this package for this specific feature (xrdp) I would want to do the following “Advanced APK Usage“:

doas apk add xrdp=0.10.1-r0

This results in the feedback from apk as:

(1/2) Updating pinning xrdp (0.10.1-r0)
(2/2) Updating pinning xrdp-openrc (0.10.1-r0)
…

Now, I can be sure that my working xRDP package versions stays the same and hopefully continues to keep working (yes, I will need to repeat this process for xorgxrdp as well, but you get the idea).

---

Setup for Alpine Linux

Upgrade and Customize Your Alpine Linux Terminal / Shell Experience

Something that really bothered me about Alpine Linux at first, was the default /bin/sh shell that is very bland and featureless compared to many other default Linux Distributions. There was no color, no username or hostname shown at the prompt and perhaps most painful of all, there was no (curly) “brace expansion”.

This is a fairly simple fix, however.

First and foremost, make sure that you have the different shell that you want to use and ready to go.

Check your CURRENT shell that is in use with:

echo $0

If this is a fresh install of Alpine Linux, then it will likely be /bin/sh or maybe /bin/ash/

Check the shell you want to change to exists in /etc/shells

cat /etc/shells

I want a bash shell, so I take note of whether or not /bin/bash is present in the list. If not, I will install it on the Alpine Linux system (replace bash with your desired choice):

doas apk add bash bash-completion

Rather than hacking at the /etc/passwd file to manually change the shell and having potentially awful consequences, lets use the safer route, like so:


# Install shadow to help us out with changing our shell
doas apk add shadow
chsh $USER

When prompted, enter /bin/bash (Or whatever else you might want)

To immediately “activate” your new shell powers, you can re-login again (but take note that doing this seems to lose all of your command history…)

su $USER

The other option is it reboot the machine and when you log in again, you should be able to use the new shell.

Verify that the new shell change is active and working, by repeating the command:

echo $0

Now try to do something that you couldn’t do before, like using {brace expansion}:

ls -haltr /etc/{apk,fstab}

• Source: https://wiki.alpinelinux.org/wiki/Change_default_shell

---

---

---

---

How to Show Logged in Username and Hostname in Shell/Terminal of Alpine Linux

Assumptions: This is either a fresh Alpine Linux installation, or there is no current configuration for PS1 in your ~/.bashrc file(s)

Append the current users ~/.bashrc file (shows as green colored):

echo "export PS1='\[\033[0;32m\]\u@\h:\[\033[36m\]\W\[\033[0m\] \$ ' " >> ~/.bashrc

then to “show” the changes, do this:

. ~/.bashrc

For your root user (shows as red colored):

echo "export PS1='\[\033[0;31m\]\u@\h:\[\033[36m\]\W\[\033[0m\] \$ ' " >> /root/.bashrc

then do:

. /root/.bashrc

Do you want a bash/shell script for this?

Sources and Reference:

• https://unix.stackexchange.com/questions/218174/how-to-show-the-host-name-in-linux-commandline-prompt
• Coloring: https://tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html