diff --git a/_data/glossary.yaml b/_data/glossary.yaml index e6039a2c75..7bbdc3cf36 100644 --- a/_data/glossary.yaml +++ b/_data/glossary.yaml @@ -199,6 +199,11 @@ overlay storage driver: | OverlayFS is a [filesystem](#filesystem) service for Linux which implements a [union mount](http://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 applied to this parent + image. A Dockerfile with no `FROM` directive has no parent image, and is called + a **base image**. registry: | A Registry is a hosted service containing [repositories](#repository) of [images](#image) which responds to the Registry API. diff --git a/compose/django.md b/compose/django.md index 77237fb870..94b3d33f11 100644 --- a/compose/django.md +++ b/compose/django.md @@ -34,8 +34,8 @@ and a `docker-compose.yml` file. (You can use either a `.yml` or `.yaml` extensi RUN pip install -r requirements.txt ADD . /code/ - This `Dockerfile` starts with a [Python 3 base image](https://hub.docker.com/r/library/python/tags/3/). - The base image is modified by adding a new `code` directory. The base image is further modified + This `Dockerfile` starts with a [Python 3 parent image](https://hub.docker.com/r/library/python/tags/3/). + The parent image is modified by adding a new `code` directory. The parent image is further modified by installing the Python requirements defined in the `requirements.txt` file. 4. Save and close the `Dockerfile`. diff --git a/cs-engine/1.12/upgrade.md b/cs-engine/1.12/upgrade.md index a1025da4e4..f605079b1a 100644 --- a/cs-engine/1.12/upgrade.md +++ b/cs-engine/1.12/upgrade.md @@ -239,7 +239,7 @@ Use these instructions to update APT-based systems. $ sudo apt-get update && sudo apt-get install apt-transport-https ``` -4. Install additional virtual drivers not in the base image. +4. Install additional virtual drivers not in the parent image. ```bash $ sudo apt-get install -y linux-image-extra-virtual diff --git a/cs-engine/1.13/upgrade.md b/cs-engine/1.13/upgrade.md index 9153f17770..7ad5a45f64 100644 --- a/cs-engine/1.13/upgrade.md +++ b/cs-engine/1.13/upgrade.md @@ -234,7 +234,7 @@ Use these instructions to update APT-based systems. $ sudo apt-get update && sudo apt-get install apt-transport-https ``` -4. Install additional virtual drivers not in the base image. +4. Install additional virtual drivers not in the parent image. ```bash $ sudo apt-get install -y linux-image-extra-virtual diff --git a/docker-store/index.md b/docker-store/index.md index cc83e2ae79..65b2835711 100644 --- a/docker-store/index.md +++ b/docker-store/index.md @@ -58,7 +58,7 @@ You can download two types of images from the Docker Store: ## What version do I need? In many cases there will be multiple versions of an image available. Some -versions may offer smaller base image sizes, or address specific security +versions may offer smaller parent image sizes, or address specific security vulnerabilities. To see a list of an image's versions, click **View all versions**. diff --git a/engine/examples/running_riak_service.Dockerfile b/engine/examples/running_riak_service.Dockerfile index 72738ade44..7aeaca3c50 100644 --- a/engine/examples/running_riak_service.Dockerfile +++ b/engine/examples/running_riak_service.Dockerfile @@ -2,7 +2,7 @@ # # VERSION 0.1.1 -# Use the Ubuntu base image provided by dotCloud +# Use the Ubuntu parent image provided by dotCloud FROM ubuntu:trusty # Install Riak repository before we do apt-get update, so that update happens diff --git a/engine/examples/running_riak_service.md b/engine/examples/running_riak_service.md index 1fe601b934..2e68662403 100644 --- a/engine/examples/running_riak_service.md +++ b/engine/examples/running_riak_service.md @@ -21,7 +21,7 @@ of. We'll use [Ubuntu](https://hub.docker.com/_/ubuntu/) (tag: # # VERSION 0.1.1 - # Use the Ubuntu base image provided by dotCloud + # Use the Ubuntu parent image provided by dotCloud FROM ubuntu:trusty After that, we install the curl which is used to download the repository setup diff --git a/engine/faq.md b/engine/faq.md index b91e07a21c..104afb9bfc 100644 --- a/engine/faq.md +++ b/engine/faq.md @@ -87,7 +87,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 [*"base image"*](reference/glossary.md#image) to create more specialized components. This can + - *Component re-use.* Any container can be used as a [*"parent image"*](reference/glossary.md#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 be re-used for all your future diff --git a/engine/security/trust/content_trust.md b/engine/security/trust/content_trust.md index 48242bece4..73eb9f8b0c 100644 --- a/engine/security/trust/content_trust.md +++ b/engine/security/trust/content_trust.md @@ -154,7 +154,7 @@ In an environment where `DOCKER_CONTENT_TRUST` is set, you can use the `--disable-content-trust` flag to run individual operations on tagged images without content trust on an as-needed basis. -Consider the following Dockerfile that uses an untrusted base image: +Consider the following Dockerfile that uses an untrusted parent image: ``` $ cat Dockerfile diff --git a/engine/tutorials/dockervolumes.md b/engine/tutorials/dockervolumes.md index 1a553cec9a..c651b4ea84 100644 --- a/engine/tutorials/dockervolumes.md +++ b/engine/tutorials/dockervolumes.md @@ -24,7 +24,7 @@ containers that bypasses the [*Union File System*](/glossary/?term=Union file sy Data volumes provide several useful features for persistent or shared data: - Volumes are initialized when a container is created. If the container's - base image contains data at the specified mount point, that existing data is + parent image contains data at the specified mount point, that existing data is copied into the new volume upon volume initialization. (Note that this does not apply when [mounting a host directory](#mount-a-host-directory-as-a-data-volume).) - Data volumes can be shared and reused among containers. diff --git a/engine/userguide/eng-image/baseimages.md b/engine/userguide/eng-image/baseimages.md index 5fddce249c..90387da26b 100644 --- a/engine/userguide/eng-image/baseimages.md +++ b/engine/userguide/eng-image/baseimages.md @@ -1,26 +1,38 @@ --- description: How to create base images -keywords: Examples, Usage, base image, docker, documentation, examples +keywords: images, base image, examples redirect_from: - /engine/articles/baseimages/ title: Create a base image --- -So you want to create your own [*Base Image*](../../reference/glossary.md#base-image)? Great! +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: -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. +- A [parent image](/reference/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. + +- A [base image](/reference/glossary.md#base-image) either has no `FROM` line + in its Dockerfile, or has `FROM scratch`. + +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. ## Create a full image using tar In general, you'll want to start with a working machine that is running -the distribution you'd like to package as a base image, though that is +the distribution you'd like to package as a parent 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 base image: +It can be as simple as this to create an Ubuntu parent image: $ sudo debootstrap raring raring > /dev/null $ sudo tar -C raring -c . | docker import - raring @@ -34,7 +46,7 @@ It can be as simple as this to create an Ubuntu base image: DISTRIB_CODENAME=raring DISTRIB_DESCRIPTION="Ubuntu 13.04" -There are more example scripts for creating base images in the Docker +There are more example scripts for creating parent images in the Docker GitHub Repo: - [BusyBox](https://github.com/moby/moby/blob/master/contrib/mkimage-busybox.sh) @@ -45,7 +57,7 @@ GitHub Repo: - [Debian / Ubuntu]( https://github.com/moby/moby/blob/master/contrib/mkimage-debootstrap.sh) -## Creating a simple base image using scratch +## Creating a simple parent 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 that you want the next command in the `Dockerfile` to be the first filesystem layer in your image. diff --git a/engine/userguide/eng-image/dockerfile_best-practices.md b/engine/userguide/eng-image/dockerfile_best-practices.md index b98d0f3802..c9287ceae8 100644 --- a/engine/userguide/eng-image/dockerfile_best-practices.md +++ b/engine/userguide/eng-image/dockerfile_best-practices.md @@ -1,6 +1,6 @@ --- description: Hints, tips and guidelines for writing clean, reliable Dockerfiles -keywords: Examples, Usage, base image, docker, documentation, dockerfile, best practices, hub, official repo +keywords: parent image, images, dockerfile, best practices, hub, official repo redirect_from: - /articles/dockerfile_best-practices/ - /engine/articles/dockerfile_best-practices/ @@ -110,7 +110,7 @@ However, if you do let Docker use its cache then it is very important to understand when it will, and will not, find a matching image. The basic rules that Docker will follow are outlined below: -* Starting with a base image that is already in the cache, the next +* Starting with a parent image that is 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. @@ -201,8 +201,8 @@ Probably the most common use-case for `RUN` is an application of `apt-get`. The out for. You should avoid `RUN apt-get upgrade` or `dist-upgrade`, as many of the -“essential” packages from the base images won't upgrade inside an unprivileged -container. If a package contained in the base image is out-of-date, you should +“essential” packages from the parent images won't upgrade inside an unprivileged +container. If a package contained in the parent image is out-of-date, you should contact its maintainers. If you know there’s a particular package, `foo`, that needs to be updated, use `apt-get install -y foo` to update automatically. diff --git a/engine/userguide/eng-image/index.md b/engine/userguide/eng-image/index.md index a77dfb0e27..b24943ac76 100644 --- a/engine/userguide/eng-image/index.md +++ b/engine/userguide/eng-image/index.md @@ -1,6 +1,6 @@ --- description: The Docker user guide home page -keywords: docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home, intro +keywords: introduction, images, dockerfile title: Work with images --- diff --git a/get-started/part2.md b/get-started/part2.md index 4c2cc22558..099f2345e2 100644 --- a/get-started/part2.md +++ b/get-started/part2.md @@ -60,7 +60,7 @@ Create an empty directory and put this file in it, with the name `Dockerfile`. Take note of the comments that explain each statement. ```conf -# Use an official Python runtime as a base image +# Use an official Python runtime as a parent image FROM python:2.7-slim # Set the working directory to /app diff --git a/machine/drivers/os-base.md b/machine/drivers/os-base.md index 3a4488f1ba..dc4a369bd8 100644 --- a/machine/drivers/os-base.md +++ b/machine/drivers/os-base.md @@ -44,7 +44,7 @@ provider's image flag and one of its available images. For example, to select a `debian-8-x64` image on DigitalOcean you would supply the `--digitalocean-image=debian-8-x64` flag. -If you change the base image for a provider, you may also need to change +If you change the parent image for a provider, you may also need to change the SSH user. For example, the default Red Hat AMI on EC2 expects the SSH user to be `ec2-user`, so you would have to specify this with -`--amazonec2-ssh-user ec2-user`. \ No newline at end of file +`--amazonec2-ssh-user ec2-user`. diff --git a/opensource/ways/test.md b/opensource/ways/test.md index 31ef2bafc2..5f0276ad64 100644 --- a/opensource/ways/test.md +++ b/opensource/ways/test.md @@ -14,7 +14,7 @@ processes. Testing is a good choice for contributors that have experience in software testing, usability testing, or who are otherwise great at spotting problems. -# What can you contribute to testing? +## What can you contribute to testing? * Write a blog about how your company uses Docker as its test infrastructure. * Take an online usability test or create a usability test about Docker. @@ -22,30 +22,29 @@ problems. * Test the Docker documentation. -# Test the Docker documentation +## Test the Docker documentation Testing documentation is relatively easy: -## Step 1. Find a page in Docker's documentation that contains a procedure or example you want to test. +1. Find a page in [Docker's documentation](/) that contains a procedure or example you want to test. -You should choose something that _should work_ on your machine. For example, -creating -a base image is something anyone with Docker can do. While changing -volume directories in Kitematic requires a Mac and Docker's Kitematic -installed. + You should choose something that _should work_ on your machine. For example, + [creating a base image](/engine/userguide/eng-image/baseimages/){: target="_blank" class="_" } + is something anyone with Docker can do, while [changing volume directories in Kitematic](https://kitematic.com/docs/managing-volumes/){: target="_blank" class="_" } + requires Kitematic installed on a Mac. -## Step 2. Try and follow the procedure or recreate the example. +2. Try and follow the procedure or recreate the example. -What to look for: + Look for: - * Are the steps clearly laid out and identifiable? - * Are the steps in the right order? - * Did you get the results the procedure or example said you would? + * Are the steps clearly laid out and identifiable? + * Are the steps in the right order? + * Did you get the results the procedure or example said you would? -## Step 3. If you couldn't complete the procedure or example, file an issue in the Docker repo. +3. If you couldn't complete the procedure or example, + [file an issue](https://github.com/moby/moby/issues/new){: target="_blank" class="_" }{: target="_blank" class="_" }. -# Test code in the Docker +## Test code in Docker If you are interested in writing or fixing test code for the Docker project, learn about our test infrastructure.