Most container images we can find in DockerHub offer an Alpine-based version, and for good reasons. If you’re not familiar with Alpine Linux already, it’s a general purpose Linux distribution built around three principles: Small, Simple and Secure.
In this article, we’ll learn how to customize Alpine-based Docker images by installing additional software we need to run our applications.
2. Add Common Software Packages
Alpine Linux is built with simplicity in mind, so to keep Docker images as small as possible, you’ll find that these containers lack even the most common software like
bash. Let’s learn how to install them.
Alpine Linux uses
apk as its package manger, and like other popular Linux distros, you’ll need to run an
apk update to build repository caches before you can search and install packages.
To add software to an Alpine-based container use the
apk add <package_name> command:
/ # apk update / # apk add curl
2.1. Installing software in Dockerfiles
When writing Dockerfiles it’s good practice making sure the final container image is as small as it can be. The
apk package manger can install software without using repository caches at all and it’s the method I recommend:
FROM apline:3.17 # Preferred method, easier to read RUN apk add --no-cache bash
The installation command above has the same effect as running an
apk update and
rm -rf /var/cache/apk after the package installation:
FROM alpine:3.17 # Same effect as the example above but using 3 commands RUN apk update \ && apk add bash \ && rm -rf /var/cache/apk
3. Search For Available Packages
If we don’t know the name of the software package in advance we can use the
apk search command to find the correct one to install. In this example we’ll install python and pip on an empty Alpine container.
First let’s open a shell in a new Alpine container with:
> docker run --rm -it alpine:3.17 /bin/sh / #
Then run an
apk update to build the repository cache and search for the python3 package:
/ # apk update / # apk search python3 ... postgresql15-plpython3-contrib-15.2-r0 python3-dbg-3.10.11-r0 python3-3.10.11-r0 <<<<<<<<<< xapian-bindings-python3-1.4.21-r0 python3-tkinter-tests-3.10.11-r0 ...
The result is a list of all packages that match our search criteria. We install python3 with:
/ # apk add python3-3.10.11-r0
You should now be able to verify the Python installation with:
/ # python3 --version Python 3.10.11
3.1. Show packages description when searching
Sometimes package names can be cryptic so it’s useful to have a short description of what we’re selecting. To see an example we’ll search for the Python3
pip package using the
/ # apk search -v pip ... execline-18.104.22.168-r0 - A small scripting language, to be used in p... pipewire-spa-bluez-0.3.61-r0 - PipeWire BlueZ5 SPA plugin (Blueto... py3-pip-22.3.1-r1 - Tool for installing and managing Python packages <<<<<<< vanessa_socket-0.0.13-r1 - User space TCP/IP pipe pipr-0.0.16-r0 - A tool to interactively write shell pipelines ...
Now that we know the name of the package is
py3-pip, we can install it and verify it works:
/ # apk add py3-pip Executing busybox-1.35.0-r29.trigger OK: 85 MiB in 34 packages / # pip --version pip 23.1.2 from /usr/lib/python3.10/site-packages/pip (python 3.10)
4. Enable Additional Package Repositories
Alpine Linux has two main package repositories:
- main packages are software that have direct support from the Alpine core maintainer
- community packages are those made and maintained by community contributors
Apk package repositories are maintained in the
/etc/apk/repositories file and by default should have two entries for main and community locations:
/ # cat /etc/apk/repositories https://dl-cdn.alpinelinux.org/alpine/v3.17/main https://dl-cdn.alpinelinux.org/alpine/v3.17/community
If you’re trying to install software from a third-party repository, or for some reason the default repos are not available, all you need to do is add them to the
Don’t forget to run the
apk updatecommand after updating the repositories list to rebuild search caches
For instance, to make sure main and community repos are enabled in a Dockerfile:
# Ensure community repository is enabled RUN VERSION="v$(cut -d'.' -f1,2 /etc/alpine-release)" \ && echo "https://dl-cdn.alpinelinux.org/alpine/$VERSION/main/" > /etc/apk/repositories \ && echo "https://dl-cdn.alpinelinux.org/alpine/$VERSION/community/" >> /etc/apk/repositories # Install additional software RUN apk update \ && apk install nginx
5. Remove Unused Software
To keep container as small and secure as possible it’s good practice to remove any software we installed and it’s not used by the final application.
To remove installed packages we use the
apk del command. For example to remove curl:
/ # apk del curl OK: 85 MiB in 34 packages
In this article, we learned how to customise Alpine-based images by installing additional software from the main and community package repositories.
A working example of a Dockerfile with the code shown in this article is available over on GitHub