Rewrite and reorganize Linux install instructions #1159
Conversation
Signed-off-by: Misty Stanley-Jones <misty@docker.com>
|
Here we goooo... |
|
I have a serious objection to this rewrite because it will result in increased support calls. All of the distro-specific support information has been removed. This needs to be restored so that Oracle (and RHEL and SUSE) customers don't think they can install upstream binaries while continuing to receive distro support for Docker. There are also inaccuracies in the Oracle text as it incorrectly refers to Red Hat. I do appreciate the simplification, though. |
|
I'll fix the Oracle text relating to Red Hat. Sorry I merged this without seeing your comment. As far as the other one, I'm really not sure what to do about this. Docker has no insight into distro-specific support arrangements with customers. We do call out that not everyone can use third-party binaries right at the top of each of these topics. |
|
Except all the distro-specific content was in the original text. You're removing a whole bunch of content without really articulating the benefit. In many cases, you're actually advocating removing the supported distro version in order to install the unsupported upstream version without even mentioning this action may cause a loss of support. |
| description: Installation instructions for Docker on Oracle Linux. | ||
| keywords: Docker, Docker documentation, requirements, linux, rhel, centos, oracle, ol | ||
| description: Instructions for installing Docker on Oracle Linux | ||
| keywords: Docker, Docker documentation, requirements, installation, oracle, oel, rpm, install, uninstall, upgrade, update |
There was a problem hiding this comment.
Please remove the oel keyword and add ol.
| - Some users download the RPM package and install it manually and manage | ||
| upgrades completely manually. | ||
|
|
||
| - Some users cannot use third-party repositories, and must rely on |
There was a problem hiding this comment.
This needs to be updated to refer to the Oracle repositories. Also, it is not clear enough that this is the preferred option for customers who wish to retain Oracle support for the docker-engine package. It needs to be clearer that this is the only supported install option by Oracle.
| - Most users | ||
| [set up the official Docker repositories](#install-using-the-repository) and | ||
| install from them, for ease of installation and upgrade tasks. This is the | ||
| recommended approach. |
There was a problem hiding this comment.
This is only the recommended approach by Docker. It is not the recommended approach by the vendor who may be providing support. It needs to be clearer that this is only recommended for customers who do not have an existing support subscription with Oracle.
|
|
||
| - Some users cannot use third-party repositories, and must rely on | ||
| the version of Docker in the Red Hat repositories. This version of Docker may | ||
| be out of date. Those users should consult the Red Hat documentation and not |
There was a problem hiding this comment.
A link to the Oracle documentation that outlines the installation and upgrade procedures should be included. It was included in the previous version of the Docker documentation.
|
|
||
| 2. Create the `docker` group. | ||
| 3. On production systems, you should install a specific version of Docker |
There was a problem hiding this comment.
You do not explain how to determine which specific version of Docker should be installed. How is the end-user supposed to determine which version of Docker to install here? Also, why shouldn't the user use the latest version of Docker? That's not explained either. Not using the latest version could leave the user vulnerable to security flaws.
There was a problem hiding this comment.
This is just saying not to always update to the latest just because it's there, but to be mindful when upgrading. This is not about which repo the bits come from. Sorry for the confusion.
|
|
||
| 5. Verify your work by running `docker` without `sudo`. | ||
| The Docker daemon starts automatically. |
There was a problem hiding this comment.
This may have changed in Docker 1.13, but up to 1.12, the daemon is not started automatically in the standard RPM. You need to use systemctl to both enable and start the Docker daemon (on OL7) or the service and chkconfig commands to start the daemon on OL6.
There was a problem hiding this comment.
You're right, I verified this behavior and updated the contents in #1172.
| On Oracle Linux 7, you can use a `systemd.mount` definition and modify the | ||
| Docker `systemd.service` to depend on the btrfs mount defined in systemd. | ||
| ```bash | ||
| $ sudo rm -rf /var/lib/docker |
There was a problem hiding this comment.
This won't work when the btrfs graph driver has been used, as the rm -rf command cannot remove the subvolumes that Docker creates.
There was a problem hiding this comment.
Thanks, I've added info about this in #1172.
| a supported platform, you can try installing from static binaries. | ||
| **This is strongly discouraged in production environments.** | ||
|
|
||
| Static binaries for the `dockerd` (Docker daemon) binary are only available for |
There was a problem hiding this comment.
dockerd.exe is also available for windows server and windows 10 (same thing).
|
|
||
| https://get.docker.com/builds/Darwin/x86_64/docker-1.11.0.tgz | ||
| ## Install server and binaries on Windows |
There was a problem hiding this comment.
Here are the instructions in a nutshell:
nvoke-WebRequest https://get.docker.com/builds/Windows/x86_64/docker-1.13.0.zip -UseBasicParsing -OutFile docker.zip
Expand-Archive docker.zip -DestinationPath $Env:ProgramFiles
Remove-Item -Force docker.zip
dockerd --register-service
Start-Service docker
|
|
||
| - To install both client and server binaries, download the 64-bit binary. The | ||
| archive includes `x86.64` in the file name. |
There was a problem hiding this comment.
it's x86_64 and it's in the path, not the filename (that goes for the client below too)
|
|
||
| To download a specific version for Windows, use the following URL pattern: | ||
| 3. **Optional**: Move the binaries to a directory on your executable path. If |
There was a problem hiding this comment.
this doesn't make sense. Instead we should tell people to change their path to include where docker is
|
|
||
| https://get.docker.com/builds/Windows/i386/docker-1.11.0.zip | ||
| > **Note**: To connect the `docker` client to a remote host, either set the |
There was a problem hiding this comment.
I don't think this is necessary - we've just taken reader through local install, they're unlikely to need this
| > The *docker* group (or the group specified with `-G`) is root-equivalent; | ||
| > see [*Docker Daemon Attack Surface*](../security/security.md#docker-daemon-attack-surface) details. | ||
| ```none | ||
| C:\> docker run hello-world |
There was a problem hiding this comment.
C:\code\tmp> docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
C:\Program Files\Docker\Docker\Resources\bin\docker.exe: image operating system "linux" cannot be used on this platform.
See 'C:\Program Files\Docker\Docker\Resources\bin\docker.exe run --help'.
The correct thing is hello-world:nanoserver
|
|
||
| - Some users cannot use third-party repositories, and must rely on the version | ||
| of Docker in the OpenSUSE or SLES repositories. This version of Docker may be | ||
| out of date. Those users should consult the CentOS documentation and not |
| $ sudo zypper install docker-engine | ||
| ``` | ||
|
|
||
| > **Warning**: If you have both stable and unstable repositories enabled, |
There was a problem hiding this comment.
This warning is duplicated, no?
There was a problem hiding this comment.
Yes once while setting up the repos and once when actually installing. It's pretty important.
|
|
||
| ## openSUSE | ||
| S | Name | Type | Version | Arch | Repository |
There was a problem hiding this comment.
@mstanleyjones as previously suggested, can we abbreviate these listings and just show a couple of rows with elipsis? I don't think there's value in listing out everything that happened to be in there when this was written.
This applies to other distros too.
| ``` | ||
|
|
||
| This script adds the `docker.repo` repository and installs Docker. | ||
| > **Warning**: If you have both stable and unstable repositories enabled, |
There was a problem hiding this comment.
@mstanleyjones why are we duplicating this warning?
There was a problem hiding this comment.
Once during enabling the repos, once when actually making the decision about what version to install.
|
I apologise if my previous tone was too abrupt or rude. I realise I am probably missing some larger context or motivation behind such large changes to the documentation. If you could, would you mind explaining the rationale behind these changes so we can better review them for the target audience? |
|
Thanks for all the feedback. Please move any more feedback to #1172. |
|
@Djelibeybi it's all good - thanks for the review and your constructive comments, it's really helpful. I also want to apologize if this seems rushed - we're crunching for a release. Ultimately, we want these docs to be short and to the point, and we want to help people install the official Docker packages that are built, supported and maintained by Docker. Further, while I'm sure that the Again, thanks for your help reviewing the docs and please keep the feedback coming. |
|
@friism I think a generic note is probably sufficient then, across the board. Something like, "These instructions install the official Docker build which may not be supported by your distribution vendor. Support for this build is available from Docker, please see..." and a link to the Docker support subscription page or product page or whatever. Essentially just to make it a little clearer to anyone who installs this particular build that support is available, but from Docker themselves. |
Proposed changes
Rewrote installation instructions for Ubuntu, Debian, RHEL, CentOS, Fedora, Oracle
Added instructions for installing from packages without using the repositories
Moved lots of non-dist-specific post-installation instructions to a new file
Added
docker.repofiles which can be imported by RHEL, CentOS, Fedora, Oracle users (the URLs to these will not work until this PR is merged)Added steps for importing and verifying the GPG signing key on all the dists where it is relevant
Reorganized content in the left-hand nav to emphasize the most popular and well-tested distros
These instructions have already undergone exhaustive review and testing.
Unreleased project version (optional)
Engine 1.13
Related issues and PRs
Fixes #703
Goes some way to eventually fixing #1026