How to Create a Custom Arch Linux Docker Image on Arch Linux

Docker is a powerful containerization platform that allows developers and system administrators to package, ship, and run applications in a lightweight, portable environment. While official Docker images exist for most popular Linux distributions—including Arch Linux—there are times when creating a custom Docker image tailored to your needs becomes necessary.

This guide walks you through the process of creating a custom Arch Linux Docker image from scratch, entirely on an Arch Linux host. Whether you want to preinstall specific packages, set custom configurations, or just understand the mechanics of Docker image creation, this tutorial has you covered.

1. Prerequisites

Before diving into the build process, make sure your system is ready:

Requirements

• A working Arch Linux host system
• Docker installed and running
• Internet access
• Basic knowledge of command-line operations

Installing Docker on Arch Linux

If you haven’t already installed Docker, you can do so using pacman:

sudo pacman -S docker
sudo systemctl enable --now docker

Verify Docker is running:

docker --version

2. Understanding the Docker Image Build Process

At its core, a Docker image is a layered file system built from a set of instructions specified in a Dockerfile. Each instruction (e.g., installing packages, copying files) forms a new layer in the image. When we build a custom Arch Linux Docker image, we are essentially:

• Creating a base Arch Linux root filesystem
• Defining a Dockerfile to layer customizations
• Building the image using docker build

Unlike some distributions, Arch Linux doesn’t provide an official debootstrap-like tool, but it does have pacstrap, which we can leverage in a chroot-like environment to generate a clean root filesystem.

3. Creating a Minimal Arch Linux Root Filesystem

We’ll use pacstrap to bootstrap a base Arch Linux filesystem into a local directory.

Step 1: Create a working directory

mkdir ~/arch-docker-image
cd ~/arch-docker-image

Step 2: Bootstrap the Arch base system

mkdir rootfs
sudo pacstrap -c -d rootfs base bash coreutils

• -c: Avoid using the host’s package cache (optional).
• -d: Do not install package documentation (makes it smaller).
• base: Installs the base Arch system.
• bash, coreutils: Ensure essential tools are present.

This will install a minimal Arch Linux environment into rootfs.

Step 3: Clean up unnecessary files

Reduce image size by removing:

sudo rm -rf rootfs/var/cache/pacman/pkg/*
sudo rm -rf rootfs/usr/share/man rootfs/usr/share/doc rootfs/usr/share/info

4. Writing the Dockerfile

Now that we have a clean Arch root filesystem, we can build our Docker image.

Step 1: Create a Dockerfile in the working directory

# Dockerfile
FROM scratch

ADD rootfs.tar.xz /

CMD ["/bin/bash"]

Explanation:

• FROM scratch: Starts from an empty base image.
• ADD rootfs.tar.xz /: Copies and unpacks our custom root filesystem into the image.
• CMD: Sets the default command to run (/bin/bash).

Step 2: Archive the root filesystem

We need to compress the rootfs directory into a tarball:

sudo tar --numeric-owner -cJf rootfs.tar.xz -C rootfs .

• --numeric-owner: Avoids user name resolution, preserving UID/GID.
• -cJf: Create, compress with xz, specify file.
• -C rootfs .: Tar everything inside the rootfs directory.

Now your working directory should contain:

Dockerfile
rootfs.tar.xz

5. Building the Custom Image

Use Docker to build the image:

docker build -t myarch:custom .

This command tells Docker to use the current directory (.) and tag the resulting image as myarch:custom.

After a short build process, you can verify the image exists:

docker images

Expected output:

REPOSITORY   TAG       IMAGE ID       CREATED              SIZE
myarch       custom    abcd1234abcd   About a minute ago   120MB

Note: Size may vary based on packages included.

6. Testing Your Custom Arch Linux Image

Now, test the image with an interactive container:

docker run -it myarch:custom

You should be dropped into a shell inside your Arch Linux container.

Try a few commands:

uname -a
pacman -Syu

Note: pacman may not work unless /etc/pacman.d/mirrorlist is properly populated. You can copy the host’s mirrorlist or manually install it during bootstrapping.

To add it:

sudo cp /etc/pacman.d/mirrorlist rootfs/etc/pacman.d/

Rebuild the image again if you make changes.

7. Tagging and Publishing (Optional)

Tag the image for Docker Hub

If you want to publish your image:

docker tag myarch:custom yourusername/arch-custom:latest

Then log in and push:

docker login
docker push yourusername/arch-custom:latest

This makes it available publicly or to your team.

8. Maintenance and Updates

Custom Docker images should be updated regularly, especially when based on a rolling-release distro like Arch Linux.

Automating Rebuilds

You can automate rebuilding the image via a script or CI pipeline.

Example shell script:

#!/bin/bash
cd ~/arch-docker-image
sudo pacstrap -c -d rootfs base bash coreutils
sudo cp /etc/pacman.d/mirrorlist rootfs/etc/pacman.d/
sudo rm -rf rootfs/var/cache/pacman/pkg/*
sudo tar --numeric-owner -cJf rootfs.tar.xz -C rootfs .
docker build -t myarch:custom .

Set a cron job or GitHub Actions pipeline to run this regularly.

9. Conclusion

Creating a custom Arch Linux Docker image on Arch Linux is straightforward when broken into steps:

• Bootstrap the base filesystem using pacstrap
• Create a Dockerfile that uses FROM scratch
• Archive your filesystem and build the image
• Test and maintain the image as needed

Arch Linux is known for its simplicity, flexibility, and cutting-edge software. These qualities make it ideal for developers who want a lean, minimal container environment tailored precisely to their use cases.

While Docker typically favors stable base images like Debian or Alpine, an Arch-based image can be powerful for rolling deployments, cutting-edge environments, and power users who know exactly what they want.

With your new custom image, you now have a foundation to build application containers, testing environments, or lightweight service containers that stay true to the Arch philosophy: Keep It Simple.