Base images
All Dockerfiles start from a base image.
A base is the image that your image extends.
It refers to the contents of the FROM
instruction in the Dockerfile.
FROM debian
For most cases, you don't need to create your own base image. Docker Hub contains a vast library of Docker images that are suitable for use as a base image in your build. Docker Official Images are specifically designed as a set of hardened, battle-tested images that support a wide variety of platforms, languages, and frameworks. There are also Docker Verified Publisher images, created by trusted publishing partners, verified by Docker.
Create a base image
If you need to completely control the contents of your image, you can create
your own base image from a Linux distribution of your choosing, or use the
special FROM scratch
base:
FROM scratch
The scratch
image is typically used to create minimal images containing only
just what an application needs. See
Create a minimal base image using scratch.
To create a distribution base image, you can use a root filesystem, packaged as
a tar
file, and import it to Docker with docker import
. The process for
creating your own base image depends on the Linux distribution you want to
package. See
Create a full image using tar.
Create a minimal base image using scratch
The reserved, minimal scratch
image serves as a starting point for
building containers. Using the scratch
image signals to the build process
that you want the next command in the Dockerfile
to be the first filesystem
layer in your image.
While scratch
appears in Docker's
repository on Docker Hub,
you can't pull it, run it, or tag any image with the name scratch
.
Instead, you can refer to it in your Dockerfile
.
For example, to create a minimal container using scratch
:
# syntax=docker/dockerfile:1
FROM scratch
ADD hello /
CMD ["/hello"]
Assuming an executable binary named hello
exists at the root of the
build context.
You can build this Docker image using the following docker build
command:
$ docker build --tag hello .
To run your new image, use the docker run
command:
$ docker run --rm hello
This example image can only successfully execute as long as the hello
binary
doesn't have any runtime dependencies. Computer programs tend to depend on
certain other programs or resources to exist in the runtime environment. For
example:
- Programming language runtimes
- Dynamically linked C libraries
- CA certificates
When building a base image, or any image, this is an important aspect to
consider. And this is why creating a base image using FROM scratch
can be
difficult, for anything other than small, simple programs. On the other hand,
it's also important to include only the things you need in your image, to
reduce the image size and attack surface.
Create a full image using tar
In general, start with a working machine that is running the distribution you'd like to package as a base image, though that is not required for some tools like Debian's Debootstrap, which you can also use to build Ubuntu images.
For example, to create an Ubuntu base image:
$ sudo debootstrap focal focal > /dev/null
$ sudo tar -C focal -c . | docker import - focal
sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3
$ docker run focal cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=20.04
DISTRIB_CODENAME=focal
DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS"
There are more example scripts for creating base images in the Moby GitHub repository.
More resources
For more information about building images and writing Dockerfiles, see: