From a28c34eeaad01209816977856420abcaa9da0cf2 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 9 Apr 2024 13:17:55 +0200 Subject: [PATCH 1/4] glossary: update base image definition, remove parent image Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- data/glossary.yaml | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/data/glossary.yaml b/data/glossary.yaml index 5efee9df9b..36ba36c059 100644 --- a/data/glossary.yaml +++ b/data/glossary.yaml @@ -4,8 +4,6 @@ arm64: | ARM64 is the 64-bit extension of the ARM CPU architecture. arm64 architecture is used in Apple silicon machines. -base image: | - A base image has no parent image specified in its Dockerfile. It is created using a Dockerfile with the `FROM scratch` directive. btrfs: | btrfs (B-tree file system) is a Linux [filesystem](#filesystem) that Docker supports as a storage backend. It is a [copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write) filesystem. @@ -197,11 +195,11 @@ overlay storage driver: | OverlayFS is a [filesystem](#filesystem) service for Linux which implements a [union mount](https://en.wikipedia.org/wiki/Union_mount) for other file systems. It is supported by the Docker daemon as a storage driver. -parent image: | - An image's parent image is the image designated in the `FROM` directive - in the image's Dockerfile. All subsequent commands are based on this parent - image. A Dockerfile with the `FROM scratch` directive uses no parent image, and creates - a base image. +base image: | + A base image is an image you designate in a `FROM` directive in a Dockerfile. + It defines the starting point for your build. + Dockerfile instructions create additional layers on top of the base image. + A Dockerfile with the `FROM scratch` directive uses an empty base image. persistent storage: | Persistent storage or volume storage provides a way for a user to add a persistent layer to the running container's file system. This persistent layer From bc950c4183bb9a45a32f97a96c3d9b7727dac12c Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 9 Apr 2024 13:59:24 +0200 Subject: [PATCH 2/4] build: update terminology related to base images Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/build/building/base-images.md | 123 +++++++++++++------------- content/build/cache/invalidation.md | 2 +- content/engine/faq.md | 2 +- 3 files changed, 65 insertions(+), 62 deletions(-) diff --git a/content/build/building/base-images.md b/content/build/building/base-images.md index f17b341f66..8bb2287807 100644 --- a/content/build/building/base-images.md +++ b/content/build/building/base-images.md @@ -9,58 +9,67 @@ aliases: - /develop/develop-images/baseimages/ --- -Most Dockerfiles start from a parent image. If you need to completely control -the contents of your image, you might need to create a base image instead. -Here's the difference: +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. -- A [parent image](../../glossary.md#parent-image) is the image that your - image is based on. It refers to the contents of the `FROM` directive in the - Dockerfile. Each subsequent declaration in the Dockerfile modifies this parent - image. Most Dockerfiles start from a parent image, rather than a base image. - However, the terms are sometimes used interchangeably. +The following Dockerfile example uses the `python` Docker Official Image as a base image. +Each subsequent instruction in the Dockerfile extends the base image. -- A [base image](../../glossary.md#base-image) has `FROM scratch` in its Dockerfile. +```dockerfile +FROM python:3-alpine +WORKDIR /src +COPY requirements.txt . +RUN pip install -r requirements.txt +``` -This topic shows you several ways to create a base image. The specific process -will depend heavily on the Linux distribution you want to package. We have some -examples below, and you are encouraged to submit pull requests to contribute new -ones. +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: + +```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. ## 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 parent image, though that is +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. -It can be as simple as this to create an Ubuntu parent image: +For example, to create an Ubuntu base image: - $ sudo debootstrap focal focal > /dev/null - $ sudo tar -C focal -c . | docker import - focal +```dockerfile +$ sudo debootstrap focal focal > /dev/null +$ sudo tar -C focal -c . | docker import - focal - sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3 +sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3 - $ docker run focal cat /etc/lsb-release +$ docker run focal cat /etc/lsb-release - DISTRIB_ID=Ubuntu - DISTRIB_RELEASE=20.04 - DISTRIB_CODENAME=focal - DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS" +DISTRIB_ID=Ubuntu +DISTRIB_RELEASE=20.04 +DISTRIB_CODENAME=focal +DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS" +``` -There are more example scripts for creating parent images in -[the Docker GitHub repository](https://github.com/docker/docker/blob/master/contrib). +There are more example scripts for creating base images in +[the Moby GitHub repository](https://github.com/moby/moby/blob/master/contrib). -## Create a simple parent image using scratch +## Create a minimal base image using scratch -You can use Docker's reserved, minimal image, `scratch`, as a starting point for -building containers. Using the `scratch` "image" signals to the build process +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 the 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`: +While `scratch` appears in Docker's [repository on Docker Hub](https://hub.docker.com/_/scratch), +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`: ```dockerfile # syntax=docker/dockerfile:1 @@ -69,46 +78,40 @@ ADD hello / CMD ["/hello"] ``` -Assuming you built the `hello` executable example by using the source code at -[https://github.com/docker-library/hello-world](https://github.com/docker-library/hello-world), -and you compiled it with the `-static` flag, you can build this Docker -image using this `docker build` command: +Assuming an executable binary named `hello` exists at the root of the [build context](../../build/building/context.md). +You can build this Docker image using the following `docker build` command: ```console $ docker build --tag hello . ``` -Don't forget the `.` character at the end, which sets the [build context](../../build/building/context.md) -to the current directory. - -> **Note** -> -> Because Docker Desktop for Mac and Docker Desktop for Windows use a Linux VM, -> you need a Linux binary, rather than a Mac or Windows binary. -> You can use a Docker container to build it: -> -> ```console -> $ docker run --rm -it -v $PWD:/build ubuntu:20.04 -> -> container# apt-get update && apt-get install build-essential -> container# cd /build -> container# gcc -o hello -static hello.c -> ``` - To run your new image, use the `docker run` command: ```console $ docker run --rm hello ``` -This example creates the hello-world image used in the tutorials. -If you want to test it out, you can clone [the image repo](https://github.com/docker-library/hello-world). +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. 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). ## More resources -There are lots of resources available to help you write your `Dockerfile`. +For more information about building images and writing Dockerfiles, see: -* There's a [complete guide to all the instructions](../../reference/dockerfile.md) available for use in a `Dockerfile` in the reference section. -* To help you write a clear, readable, maintainable `Dockerfile`, we've also - written a [Dockerfile best practices guide](../../build/building/best-practices.md). -* If your goal is to create a new Docker Official Image, read [Docker Official Images](../../trusted-content/official-images/_index.md). +* [Dockerfile reference](../../reference/dockerfile.md) +* [Dockerfile best practices](../../build/building/best-practices.md) +* [Docker Official Images](../../trusted-content/official-images/_index.md) diff --git a/content/build/cache/invalidation.md b/content/build/cache/invalidation.md index 0482128ff6..a55f5438ec 100644 --- a/content/build/cache/invalidation.md +++ b/content/build/cache/invalidation.md @@ -12,7 +12,7 @@ checks whether it can reuse the instruction from the build cache. The basic rules of build cache invalidation are as follows: -- Starting with a parent image that's already in the cache, the next +- Starting with a base image that's already in the cache, the next instruction is compared against all child images derived from that base image to see if one of them was built using the exact same instruction. If not, the cache is invalidated. diff --git a/content/engine/faq.md b/content/engine/faq.md index 273bd6a990..b526929a89 100644 --- a/content/engine/faq.md +++ b/content/engine/faq.md @@ -56,7 +56,7 @@ offers a high-level tool with several powerful functionalities: uploads and downloads, similar to `git pull`, so new versions of a container can be transferred by only sending diffs. - - *Component re-use.* Any container can be used as a [*parent image*](../glossary.md#parent-image) to + - *Component re-use.* Any container can be used as a [base image](../glossary.md#base-image) to create more specialized components. This can be done manually or as part of an automated build. For example you can prepare the ideal Python environment, and use it as a base for 10 different applications. Your ideal PostgreSQL setup can From 2bd964d6afd7a99c94140efa35460859f66fa8e2 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 17 May 2024 12:34:19 +0200 Subject: [PATCH 3/4] build: restructure the base image page Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/build/building/base-images.md | 86 ++++++++++--------- .../building-images/multi-stage-builds.md | 2 +- .../building-images/writing-a-dockerfile.md | 2 +- content/language/golang/build-images.md | 2 +- data/toc.yaml | 2 +- 5 files changed, 51 insertions(+), 43 deletions(-) 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/ From 8479834c27e0d6075548b1aaaaadfcc24ed2871f Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 17 May 2024 12:37:05 +0200 Subject: [PATCH 4/4] vale: add Debootstrap to vocabulary Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .github/vale/config/vocabularies/Docker/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/vale/config/vocabularies/Docker/accept.txt b/.github/vale/config/vocabularies/Docker/accept.txt index a40c7652cc..7d5276300e 100644 --- a/.github/vale/config/vocabularies/Docker/accept.txt +++ b/.github/vale/config/vocabularies/Docker/accept.txt @@ -29,6 +29,7 @@ DSOS DVP Datadog Ddosify +Debootstrap Dev Environments? Django Docker