How to Use the BusyBox Docker Official Image

The size of your image can have a significant impact on the speed and size of your application. Slimmer images will not only speed up build times, but they’ll also help optimize your application’s footprint. But successfully deploying compact, Linux-friendly applications means packaging them into a cross-platform unit. That’s where containers and the BusyBox Docker Official Image come in handy.

The BusyBox container image is incredibly lightweight. With most tags being under 900KB (depending on architecture), it’s even smaller than our Alpine image, which developers gravitate towards given its slimness. 

BusyBox’s compact size enables quicker sharing, by greatly reducing initial upload and download times. This smaller base image can also reduce your application’s attack surface.

In this guide, we’ll show you BusyBox, explain its uses, share best practices, and show you how to use its container image.

What is BusyBox?

People often refer to this open source project as the “Swiss Army Knife of Embedded Linux“. BusyBox packages multiple, common UNIX utilities (or applets) into one executable binary. This allows you to make your own Linux distribution. And the Docker image lets you use BusyBox in a variety of different environments. 

Miniature but mighty, this single executable contains nearly 400 of UNIX’s leading commands. It also replaces many GNU utilities (ex. shellutils and fileutils) with something comparable in its full distribution. Some may lack full features, but their main functions remain intact and don’t force developers to compromise.

Which BusyBox version should I use?

BusyBox helps replicate the experience of using common shell commands. Some Linux distributions use GNU’s coreutils package to ship these commands, while others have instead opted for BusyBox. It’s not the most complete environment but perfect for developers needing an easy-to-use and lightweight environment.

This software suite comes in a variety of pre-built binary versions, and we support over 30 image tags on Docker Hub. Each includes its own Linux binary variant per CPU and dependencies and will vary in image size and functionality.

Each image tag is also built against various libc variants. To understand how each image’s relation to musl, uClibc, dietlibc, and glibc impacts your build, check out this comparison chart. This’ll help you choose the correct image for your specific use case.

That being said, what is BusyBox best used for? Let’s jump in.

BusyBox use cases

While developer use cases for Linux will vary pretty greatly, there are a few interesting examples we’ll cover here.

1. Build distros for embedded systems

Embedded systems are known for having limited available resources and require distributions with minute sizes that only include essential functionality. There’s little extra room for frills or extra dependencies. So it’s best for embedded Linux versions to be streamlined and purpose-built. This is where BusyBox excels.

BusyBox is fairly modular. You can choose any of its images that suit your build. But you can also pick commands or features during compilation.

You don’t have to package together anything you don’t need (to a degree). Normally, you would run atop the Linux kernel. But containerizing your implementation removes the need to include this kernel within the container itself. BusyBox will instead leverage your embedded system’s kernel, saving space.

Each applet’s behavior within your given image will determine how it works within a given embedded environment. BusyBox lets you modify configuration files, directories, and infrastructure to best fit your embedded system of choice.

2. Leverage Kubernetes Init containers

The BusyBox Docker Official Image also works well with the Kubernetes initContainer feature. These specialized containers (for our example) run before app containers in a Pod.

Init containers can contain scripts or other utilities outside the application image. Initializing these “regular” containers may depend on k8s spinning up these components first. But they always run synchronously and until their tasks finish.

These containers also adhere to strictly configured resource limits, support volumes, and respect your security settings. 

But what can you use an initContainer for? According to the k8s documentation, you can:

• Wait for a Service to be created as Pods spin up
• Register a Pod with a remote server from an API
• Wait for an allotted period before finally starting an app container
• Clone a Git repo into a volume
• Generate configuration files automatically from value inputs

Kubernetes uses its configuration files to specify how these processes occur — alongside any shell commands. You can specify your BusyBox Docker image in this file with your chosen tag. Kubernetes will pull your image, and then create and start containers from it while assigning them unique IDs.

Using init containers with BusyBox and Docker allows you to prepare app containers for important workflows before they start.

3. Run an HTTP Web Server

Remember how we mentioned that the BusyBox container image helps you create a basic Linux environment? We can use that environment to run compiled Linux applications and create custom executables. Then, these executables can support a web app!

For example, developer Soham Kamani uses this method to support a web app powered by a Go server. Soham accomplished this by:

1. Creating a BusyBox container using the Docker CLI to run common commands.
2. Running custom executables after creating a custom Golang “hello world” program, and creating a companion Dockerfile to support it.
3. Building and running a Docker image using BusyBox as the base.
4. Creating a server.go file, compiling it, and running it as a web server using Docker components.

BusyBox lets you tackle this workflow and create a slim, final image. It creates an environment where applications can run, thrive, scale, and deploy effectively. You can even manage your images and containers easily with Docker Desktop if you prefer a visual interface.

You can read through the entire tutorial, and view the sample code on GitHub. Want to explore more Go-based server deployments? Check out our Caddy 2 image guide.

This isn’t an exhaustive list of BusyBox use cases. But these examples do showcase how creative you can get, even with a simple Linux-based image.

Get started with the BusyBox image

Now that we have explored its functionality, let’s learn how to install BusyBox and start using it with Docker.

Step 1: Run your Docker image

First, run BusyBox as a shell with the following command:

$ docker run -it --rm busybox

This lets you execute commands within your BusyBox system since you’re now effectively sh-ing into your environment. The -it flag combines both -i and -t together — which keeps STDIN open and allocates a pseudo-tty. This -tty tells Docker to create a virtual terminal session within your container. Using the --rm flag tells Docker to tidy up your container and remove the filesystem when it exits.

Step 2: Create your Dockerfile

Next, you’ll create a Dockerfile for your statically-compiled binary. Here’s how that basic BusyBox Dockerfile could look:

FROM busybox
COPY ./my-static-binary /my-static-binary
CMD ["/my-static-binary"]

Note: You’ll have to complete this compilation in another location, like a Docker container. You can use Alpine, but you can use BusyBox instead if you won’t need extended capabilities.

Step 3: Choose your variant

Lastly, always choose the variant which best fits your needs. You can use either:

1. busybox:uclibc
2. busybox:glibc
3. busybox:musl

Options one and three statically compile, while glibc stems from Debian.

Docker and BusyBox equal simplicity

BusyBox is an essential tool for developers who love simplistic Linux. It lets you create powerful, customized Linux executables within a stripped-down (yet adaptable) Linux environment. Use cases are diverse, and the BusyBox image helps reduce bloat.

Both Docker and BusyBox work well together while being inclusive of popular, related technologies like Kubernetes. Despite the image’s small size, it unlocks many exciting development possibilities that are always evolving. Visit Docker Hub to learn more and quickly pull your first BusyBox image.