mirror of https://github.com/docker/docs.git
build: update terminology related to base images
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson
parent
a28c34eeaa
commit
bc950c4183
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue