Tighten up base image and parent image terminology (#3720)

_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.

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`.

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

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

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**.

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

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

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

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

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.

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.
 

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.

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
 ---
 

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

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`.
+`--amazonec2-ssh-user ec2-user`.

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 <a href="http://www.appneta.com/blog/automated-testing-with-docker/" target="_blank">how your company uses Docker as its test infrastructure</a>.
 * Take <a href="http://ows.io/tj/w88v3siv" target="_blank">an online usability test</a> 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 <a href="/" target="_blank">Docker's documentation</a> 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,
-<a href="/engine/userguide/eng-image/baseimages/" target="_blank">creating
-a base image</a> is something anyone with Docker can do. While <a
-href="https://kitematic.com/docs/managing-volumes/" target="_blank">changing
-volume directories in Kitematic</a> 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 <a href="https://github.com/moby/moby/issues/new" target="_blank">an issue in the Docker repo</a>.
+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  <a href="/opensource/project/test-and-docs/" target="_blank">our test infrastructure</a>.