diff --git a/content/build/building/base-images.md b/content/build/building/base-images.md index 8bb2287807..7bb891144c 100644 --- a/content/build/building/base-images.md +++ b/content/build/building/base-images.md @@ -1,5 +1,5 @@ --- -title: Create a base image +title: Base images description: Learn about base images and how they're created keywords: images, base image, examples aliases: @@ -13,51 +13,35 @@ 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. -The following Dockerfile example uses the `python` Docker Official Image as a base image. -Each subsequent instruction in the Dockerfile extends the base image. - ```dockerfile -FROM python:3-alpine -WORKDIR /src -COPY requirements.txt . -RUN pip install -r requirements.txt +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](../../trusted-content/official-images/_index.md) +are specifically designed as a set of hardened, battle-tested images that +supports a wide variety of platforms, languages, and frameworks. There are also +[Docker Verified Publisher](https://hub.docker.com/search?q=&image_filter=store) +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 or use the special `FROM scratch` base: +your own base image from a Linux distribution of your choosing, or use the +special `FROM scratch` base: ```dockerfile FROM scratch ``` -This page shows you how to create your own base image. -The specific process depends on the Linux distribution you want to package. +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](#create-a-minimal-base-image-using-scratch). -## 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](https://wiki.debian.org/Debootstrap), -which you can also use to build Ubuntu images. - -For example, to create an Ubuntu base image: - -```dockerfile -$ 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](https://github.com/moby/moby/blob/master/contrib). +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-full-image-using-tar). ## Create a minimal base image using scratch @@ -104,9 +88,33 @@ 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. In most cases, your best option is -to base your images on a suitable tag of a -[Docker Official Image](../../trusted-content/official-images.md). +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](https://wiki.debian.org/Debootstrap), +which you can also use to build Ubuntu images. + +For example, to create an Ubuntu base image: + +```dockerfile +$ 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](https://github.com/moby/moby/blob/master/contrib). ## More resources diff --git a/content/guides/docker-concepts/building-images/multi-stage-builds.md b/content/guides/docker-concepts/building-images/multi-stage-builds.md index d0db2f3835..ad92bde248 100644 --- a/content/guides/docker-concepts/building-images/multi-stage-builds.md +++ b/content/guides/docker-concepts/building-images/multi-stage-builds.md @@ -325,7 +325,7 @@ Now that you have the project, you’re ready to create the `Dockerfile`. * [Multi-stage builds](/build/building/multi-stage/) * [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/) -* [Creating a base image](/build/building/base-images/) +* [Base images](/build/building/base-images/) * [Spring Boot Docker](https://spring.io/guides/topicals/spring-boot-docker) diff --git a/content/guides/docker-concepts/building-images/writing-a-dockerfile.md b/content/guides/docker-concepts/building-images/writing-a-dockerfile.md index bb25d19064..e806704f15 100644 --- a/content/guides/docker-concepts/building-images/writing-a-dockerfile.md +++ b/content/guides/docker-concepts/building-images/writing-a-dockerfile.md @@ -142,7 +142,7 @@ To learn more about writing a Dockerfile, visit the following resources: * [Dockerfile reference](/reference/dockerfile/) * [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/) -* [Create your own base image](/build/building/base-images/) +* [Base images](/build/building/base-images/) * [Getting started with Docker Init](/reference/cli/docker/init/) ## Next steps diff --git a/content/language/golang/build-images.md b/content/language/golang/build-images.md index 4029e1fe3a..f99be92daf 100644 --- a/content/language/golang/build-images.md +++ b/content/language/golang/build-images.md @@ -113,7 +113,7 @@ has all necessary tools and libraries to compile and run a Go application. > **Note** > -> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](../../build/building/base-images.md). +> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](../../build/building/base-images.md#create-a-base-image). > Note, however, that this isn't necessary to continue with your task at hand. Now that you have defined the base image for your upcoming container image, you diff --git a/data/toc.yaml b/data/toc.yaml index fc5578f023..c505309e6a 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1884,7 +1884,7 @@ Manuals: - path: /build/building/opentelemetry/ title: OpenTelemetry support - path: /build/building/base-images/ - title: Create your own base image + title: Base images - sectiontitle: Builders section: - path: /build/builders/