Installation guide improvements (docker#3977)

Author: Misty Stanley-Jones

_data/toc.yaml

@@ -52,6 +52,12 @@ guides:
       title: Fedora
     - path: /engine/installation/linux/docker-ce/binaries/
       title: Binaries
+  - sectiontitle: Platforms supporting Docker EE and Docker CE
+    section:
+    - path: /engine/installation/linux/centos/
+      title: CentOS
+    - path: /engine/installation/linux/ubuntu/
+      title: Ubuntu
   - path: /engine/installation/linux/linux-postinstall/
     title: Optional Linux post-installation steps
   - sectiontitle: Docker Edge

_includes/docker_platform_matrix.md

@@ -1,12 +1,12 @@
 {% assign green-check = '![yes](/engine/installation/images/green-check.svg){: style="height: 14px; margin: 0 auto"}' %}
 {% assign install-prefix = '/engine/installation/linux' %}
-| Platform                                                                   | Docker CE x86_64                                              | Docker CE ARM                                                 | Docker EE                                                      |
-|:---------------------------------------------------------------------------|:--------------------------------------------------------------|:--------------------------------------------------------------|:---------------------------------------------------------------|
-| [CentOS]({{ install-prefix }}/centos.md)                                   | [{{ green-check }}]({{ install-prefix }}/docker-ce/centos.md) |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/centos.md)  |
-| [Debian]({{ install-prefix }}/docker-ce/debian.md)                         | [{{ green-check }}]({{ install-prefix }}/docker-ce/debian.md) | [{{ green-check }}]({{ install-prefix }}/docker-ce/debian.md) |                                                                |
-| [Fedora]({{ install-prefix }}/docker-ce/fedora.md)                         | [{{ green-check }}]({{ install-prefix }}/docker-ce/fedora.md) |                                                               |                                                                |
-| [Microsoft Windows Server 2016](/engine/installation/windows/docker-ee.md) |                                                               |                                                               | [{{ green-check }}](/engine/installation/windows/docker-ee.md) |
-| [Oracle Linux]({{ install-prefix }}/docker-ee/oracle.md)                   |                                                               |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/oracle.md)  |
-| [Red Hat Enterprise Linux]({{ install-prefix }}/docker-ee/rhel.md)         |                                                               |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/rhel.md)    |
-| [SUSE Linux Enterprise Server]({{ install-prefix }}/docker-ee/suse.md)     |                                                               |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/suse.md)    |
-| [Ubuntu]({{ install-prefix }}/ubuntu.md)                                   | [{{ green-check }}]({{ install-prefix }}/docker-ce/ubuntu.md) | [{{ green-check }}]({{ install-prefix }}/docker-ce/ubuntu.md) | [{{ green-check }}]({{ install-prefix }}/docker-ee/ubuntu.md)  |
+| Platform                                                                   | Docker CE x86_64                                              | Docker CE ARM                                                 | Docker CE System Z (s390x)                                    | Docker EE                                                      |
+|:---------------------------------------------------------------------------|:--------------------------------------------------------------|:--------------------------------------------------------------|:--------------------------------------------------------------|:---------------------------------------------------------------|
+| [CentOS]({{ install-prefix }}/centos.md)                                   | [{{ green-check }}]({{ install-prefix }}/docker-ce/centos.md) |                                                               |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/centos.md)  |
+| [Debian]({{ install-prefix }}/docker-ce/debian.md)                         | [{{ green-check }}]({{ install-prefix }}/docker-ce/debian.md) | [{{ green-check }}]({{ install-prefix }}/docker-ce/debian.md) |                                                               |                                                                |
+| [Fedora]({{ install-prefix }}/docker-ce/fedora.md)                         | [{{ green-check }}]({{ install-prefix }}/docker-ce/fedora.md) |                                                               |                                                               |                                                                |
+| [Microsoft Windows Server 2016](/engine/installation/windows/docker-ee.md) |                                                               |                                                               |                                                               | [{{ green-check }}](/engine/installation/windows/docker-ee.md) |
+| [Oracle Linux]({{ install-prefix }}/docker-ee/oracle.md)                   |                                                               |                                                               |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/oracle.md)  |
+| [Red Hat Enterprise Linux]({{ install-prefix }}/docker-ee/rhel.md)         |                                                               |                                                               |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/rhel.md)    |
+| [SUSE Linux Enterprise Server]({{ install-prefix }}/docker-ee/suse.md)     |                                                               |                                                               |                                                               | [{{ green-check }}]({{ install-prefix }}/docker-ee/suse.md)    |
+| [Ubuntu]({{ install-prefix }}/ubuntu.md)                                   | [{{ green-check }}]({{ install-prefix }}/docker-ce/ubuntu.md) | [{{ green-check }}]({{ install-prefix }}/docker-ce/ubuntu.md) | [{{ green-check }}]({{ install-prefix }}/docker-ce/ubuntu.md) | [{{ green-check }}]({{ install-prefix }}/docker-ee/ubuntu.md)  |

_includes/install-script.md

@@ -0,0 +1,66 @@
+<!-- This file is included in Docker CE or EE installation docs for Linux. -->
+
+### Install using the convenience script
+
+Docker provides convenience scripts at [get.docker.com](https://get.docker.com/)
+and [test.docker.com](https://test.docker.com/) for installing stable and
+testing versions of Docker CE into development environments quickly and
+non-interactively. The source code for the scripts is in the
+[`docker-install` repository](https://github.com/docker/docker-install).
+**Using these scripts is not recommended for production
+environments**, and you should understand the potential risks before you use
+them:
+
+- The scripts require `root` or `sudo` privileges in order to run. Therefore,
+  you should carefully examine and audit the scripts before running them.
+- The scripts attempt to detect your Linux distribution and version and
+  configure your package management system for you. In addition, the scripts do
+  not allow you to customize any installation parameters. This may lead to an
+  unsupported configuration, either from Docker's point of view or from your own
+  organization's guidelines and standards.
+- The scripts install all dependencies and recommendations of the package
+  manager without asking for confirmation. This may install a large number of
+  packages, depending on the current configuration of your host machine.
+- Do not use the convenience script if Docker has already been installed on the
+  host machine using another mechanism.
+
+This example uses the script at [get.docker.com](https://get.docker.com/) to
+install the latest stable release of Docker CE on Linux. To install the latest
+testing version, use [test.docker.com](https://test.docker.com/) instead. In
+each of the commands below, replace each occurrence of `get` with `test`.
+
+> **Warning**: Always examine scripts downloaded from the internet  before
+> running them locally.
+{:.warning-vanilla}
+
+```bash
+$ curl -fsSL get.docker.com -o get-docker.sh
+$ sudo sh get-docker.sh
+
+<output truncated>
+
+If you would like to use Docker as a non-root user, you should now consider
+adding your user to the "docker" group with something like:
+
+  sudo usermod -aG docker your-user
+
+Remember that you will have to log out and back in for this to take effect!
+
+WARNING: Adding a user to the "docker" group will grant the ability to run
+         containers which can be used to obtain root privileges on the
+         docker host.
+         Refer to https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface
+         for more information.
+```
+
+Docker CE is installed. It starts automatically on `DEB`-based distributions. On
+`RPM`-based distributions, you need to start it manually using the appropriate
+`systemctl` or `service` command. As the message indicates, non-root users are
+not able to run Docker commands by default.
+
+#### Upgrade Docker after using the convenience script
+
+If you installed Docker using the convenience script, you should upgrade Docker
+using your package manager directly. There is no advantage to re-running the
+convenience script, and it can cause issues if it attempts to re-add
+repositories which have already been added to the host machine.

engine/installation/linux/centos.md

@@ -4,7 +4,8 @@ title: Choose Docker CE or Docker EE on CentOS
 ---
 
 The instructions for installing Docker on CentOS depend on whether you are using
-Docker EE or Docker CE.
+Docker Enterprise Edition (Docker EE) or Docker Community Edition (Docker CE).
+[Learn more about Docker EE and Docker CE](/engine/installation/).
 
 - [Install Docker EE on CentOS](/engine/installation/linux/docker-ee/centos.md)
 - [Install Docker CE on CentOS](/engine/installation/linux/docker-ce/centos.md)

engine/installation/linux/docker-ce/binaries.md

@@ -72,23 +72,19 @@ instructions for enabling and configuring AppArmor or SELinux.
 
 ### Install static binaries
 
-1.  Download the static binary archive. You can download either the latest
-    release binaries or a specific version. To find the download link, see the
-    [release notes](https://github.com/moby/moby/releases) for the version
-    of Docker you want to install. You can choose a `tar.gz` archive or `zip`
-    archive.
+1.  Download the static binary archive. Go to
+    [https://download.docker.com/linux/static/stable/](https://download.docker.com/linux/static/stable/x86_64/)
+    (or change `stable` to `edge` or `test`),
+    choose your hardware platform, and download the `.tgz` file relating to the
+    version of Docker CE you want to install.
 
-2.  Extract the archive using `tar` or `unzip`, depending on the format you
-    downloaded. The `dockerd` and `docker` binaries are extracted.
+2.  Extract the archive using the `tar` utility. The `dockerd` and `docker`
+    binaries are extracted.
 
     ```bash
     $ tar xzvf /path/to/<FILE>.tar.gz
     ```
 
-    ```bash
-    $ unzip /path/to/<FILE>.zip
-    ```
-
 3.  **Optional**: Move the binaries to a directory on your executable path, such
     as `/usr/bin/`. If you skip this step, you must provide the path to the
     executable when you invoke `docker` or `dockerd` commands.
@@ -104,7 +100,8 @@ instructions for enabling and configuring AppArmor or SELinux.
     ```
 
     If you need to start the daemon with additional options, modify the above
-    command accordingly.
+    command accordingly or create and edit the file `/etc/docker/daemon.json`
+    to add the custom configuration options.
 
 5.  Verify that Docker is installed correctly by running the `hello-world`
     image.
@@ -127,23 +124,20 @@ instructions for enabling and configuring AppArmor or SELinux.
 The macOS binary includes the Docker client only. It does not include the
 `dockerd` daemon.
 
-1.  Download the static binary archive. You can download either the latest
-    release binaries or a specific version. To find the download link, see the
-    [release notes](https://github.com/moby/moby/releases) for the version
-    of Docker you want to install. You can choose a `tar.gz` archive or
-    `zip` archive.
+1.  Download the static binary archive. Go to
+    [https://download.docker.com/mac/static/stable/x86_64/](https://download.docker.com/mac/static/stable/x86_64/),
+    (or change `stable` to `edge` or `test`),
+    and download the `.tgz` file relating to the version of Docker CE you want
+    to install.
 
-2.  Extract the archive using `tar` or `unzip`, depending on the format you
-    downloaded. The `docker` binary is extracted.
+2.  Extract the archive using the `tar` utility. The `docker` binary is
+    extracted.
 
     ```bash
     $ tar xzvf /path/to/<FILE>.tar.gz
     ```
 
-    ```bash
-    $ unzip /path/to/<FILE>.zip
-    ```
-3.  **Optional**: Move the binaries to a directory on your executable path, such
+3.  **Optional**: Move the binary to a directory on your executable path, such
     as `/usr/local/bin/`. If you skip this step, you must provide the path to the
     executable when you invoke `docker` or `dockerd` commands.
 
@@ -152,7 +146,8 @@ The macOS binary includes the Docker client only. It does not include the
     ```
 
 4.  Verify that Docker is installed correctly by running the `hello-world`
-    image.
+    image. The value of `<hostname>` is a hostname or IP address running the
+    Docker daemon and accessible to the client.
 
     ```bash
     $ sudo docker -H <hostname> run hello-world
@@ -164,43 +159,40 @@ The macOS binary includes the Docker client only. It does not include the
 
 ## Install server and client binaries on Windows
 
-You can install Docker from binaries on Windows Server 2016 or Windows 10.
-
-- To install both client and server binaries, download the 64-bit binary. The
-  archive includes `x86_64` in the path.
-
-- To install the client only, download the 32-bit binary. The archive includes
-  `i386` in the path.
+You can install Docker from binaries on Windows Server 2016 or Windows 10. Both
+the `dockerd.exe` and `docker.exe` binaries are included.
 
 1.  Use the following PowerShell commands to install and start Docker:
 
     ```none
-    Invoke-WebRequest https://get.docker.com/builds/Windows/x86_64/docker-{{ minor-version }}.0-ce.zip -UseBasicParsing -OutFile docker.zip
-    Expand-Archive docker.zip -DestinationPath $Env:ProgramFiles
-    Remove-Item -Force docker.zip
+    PS C:\> Invoke-WebRequest https://download.docker.com/win/static/stable/x86_64//docker-{{ minor-version }}.0-ce.zip -UseBasicParsing -OutFile docker.zip
+
+    PS C:\> Expand-Archive docker.zip -DestinationPath $Env:ProgramFiles
+
+    PS C:\> Remove-Item -Force docker.zip
 
-    dockerd --register-service
+    PS C:\> dockerd --register-service
 
-    Start-Service docker
+    PS C:\> Start-Service docker
     ```
 
 2.  Verify that Docker is installed correctly by running the `hello-world`
     image.
 
 
     ```none
-    docker run hello-world:nanoserver
+    PS C:\> docker run hello-world:nanoserver
     ```
 
     This command downloads a test image and runs it in a container. When the
     container runs, it prints an informational message and exits.
 
 ## Upgrade static binaries
 
-To upgrade your manual installation of Docker Engine on Linux, first stop any
-`dockerd` processes running locally, then follow the
-[regular installation steps](#get-the-linux-binaries), overwriting any existing
-`dockerd` or `docker` binaries with the newer versions.
+To upgrade your manual installation of Docker CE, first stop any
+`dockerd` or `dockerd.exe`  processes running locally, then follow the
+regular installation steps to install the new version on top of the existing
+version.
 
 ## Next steps
 

engine/installation/linux/docker-ce/centos.md

@@ -53,10 +53,14 @@ You can install Docker CE in different ways, depending on your needs:
   from them, for ease of installation and upgrade tasks. This is the
   recommended approach.
 
-- Some users download the RPM package and install it manually and manage
+- Some users download the RPM package and
+  [install it manually](#install-from-a-package) and manage
   upgrades completely manually. This is useful in situations such as installing
   Docker on air-gapped systems with no access to the internet.
 
+- In testing and development environments, some users choose to use automated
+  [convenience scripts](#install-using-the-convenience-script) to install Docker.
+
 ### Install using the repository
 
 Before you install Docker CE for the first time on a new host machine, you need
@@ -135,6 +139,7 @@ from the repository.
     > or updating without specifying a version in the `yum install` or
     > `yum update` command will always install the highest possible version,
     > which may not be appropriate for your stability needs.
+    {:.warning-vanilla}
 
 3.  On production systems, you should install a specific version of Docker CE
     instead of always using the latest. List the available versions. This
@@ -237,6 +242,8 @@ To upgrade Docker CE, download the newer package file and repeat the
 [installation procedure](#install-from-a-package), using `yum -y upgrade`
 instead of `yum -y install`, and pointing to the new file.
 
+{% include install-script.md %}
+
 ## Uninstall Docker CE
 
 1.  Uninstall the Docker package:

engine/installation/linux/docker-ce/debian.md

@@ -71,10 +71,14 @@ You can install Docker CE in different ways, depending on your needs:
   from them, for ease of installation and upgrade tasks. This is the
   recommended approach.
 
-- Some users download the DEB package and install it manually and manage
+- Some users download the DEB package and
+  [install it manually](#install-from-a-package) and manage
   upgrades completely manually. This is useful in situations such as installing
   Docker on air-gapped systems with no access to the internet.
 
+- In testing and development environments, some users choose to use automated
+  [convenience scripts](#install-using-the-convenience-script) to install Docker.
+
 ### Install using the repository
 
 Before you install Docker CE for the first time on a new host machine, you need
@@ -356,7 +360,7 @@ a new file each time you want to upgrade Docker.
     container runs, it prints an informational message and exits.
 
 Docker CE is installed and running. You need to use `sudo` to run Docker
-commands. Continue to [Post-installation steps for Linux](linux-postinstall.md)
+commands. Continue to [Post-installation steps for Linux](/engine/installation/linux/linux-postinstall.md)
 to allow non-privileged users to run Docker commands and for other optional
 configuration steps.
 
@@ -365,6 +369,8 @@ configuration steps.
 To upgrade Docker, download the newer package file and repeat the
 [installation procedure](#install-from-a-package), pointing to the new file.
 
+{% include install-script.md %}
+
 ## Uninstall Docker CE
 
 1.  Uninstall the Docker CE package: