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: