diff --git a/_data/toc.yaml b/_data/toc.yaml index dcbbb72cb2..2cbdc03332 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -43,28 +43,26 @@ toc: title: Release Notes - sectiontitle: Docker for Linux section: - - path: /engine/installation/linux/ubuntulinux/ - title: Installation on Ubuntu + - path: /engine/installation/linux/ubuntu/ + title: Ubuntu - path: /engine/installation/linux/rhel/ - title: Installation on Red Hat Enterprise Linux + title: Red Hat Enterprise Linux - path: /engine/installation/linux/centos/ - title: Installation on CentOS + title: CentOS - path: /engine/installation/linux/fedora/ - title: Installation on Fedora + title: Fedora - path: /engine/installation/linux/debian/ - title: Installation on Debian - - path: /engine/installation/linux/archlinux/ - title: Installation on Arch Linux - - path: /engine/installation/linux/cruxlinux/ - title: Installation on CRUX Linux - - path: /engine/installation/linux/gentoolinux/ - title: Installation on Gentoo + title: Debian - path: /engine/installation/linux/oracle/ - title: Installation on Oracle Linux - - path: /engine/installation/linux/SUSE/ - title: Installation on openSUSE and SUSE Linux Enterprise + title: Oracle Linux + - path: /engine/installation/linux/suse/ + title: OpenSuSE and SuSE Linux Enterprise + - path: /engine/installation/linux/other/ + title: Other Linux distributions - path: /engine/installation/binaries/ title: Installation from binaries + - path: /engine/installation/linux-postinstall/ + title: Optional post-installation steps - sectiontitle: Docker for AWS section: - path: /docker-for-aws/ diff --git a/engine/installation/binaries.md b/engine/installation/binaries.md index e57e003f76..1f9506355b 100644 --- a/engine/installation/binaries.md +++ b/engine/installation/binaries.md @@ -4,225 +4,199 @@ keywords: binaries, installation, docker, documentation, linux title: Install Docker from binaries --- -**This instruction set is meant for hackers who want to try out Docker -on a variety of environments.** +> **Note**: You may have been redirected to this page because there is no longer +> a dynamically-linked Docker package for your Linux distribution. -Before following these directions, you should really check if a packaged -version of Docker is already available for your distribution. We have -packages for many distributions, and more keep showing up all the time! +If you want to try Docker or use it in a testing environment, but you're not on +a supported platform, you can try installing from static binaries. +**This is strongly discouraged in production environments.** -## Check runtime dependencies +Static binaries for the `dockerd` (Docker daemon) binary are only available for +Linux. Static binaries for the `docker` (Docker client) binary are available for +Linux, MacOS, and Windows. -To run properly, docker needs the following software to be installed at -runtime: +## Install daemon and client binaries on Linux - - iptables version 1.4 or later - - Git version 1.7 or later - - procps (or similar provider of a "ps" executable) - - XZ Utils 4.9 or later - - a [properly mounted]( - https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount) - cgroupfs hierarchy (having a single, all-encompassing "cgroup" mount - point [is](https://github.com/docker/docker/issues/2683) - [not](https://github.com/docker/docker/issues/3485) - [sufficient](https://github.com/docker/docker/issues/4568)) +### Prerequisites -## Check kernel dependencies +Before attempting to install Docker from binaries, be sure your host machine +meets the prerequisites: -Docker in daemon mode has specific kernel requirements. For details, -check your distribution in [*Installation*](index.md#on-linux). +- A 64-bit installation +- Version 3.10 or higher of the Linux kernel. The latest version of the kernel + available for you platform is recommended. +- `iptables` version 1.4 or higher +- `git` version 1.7 or higher +- A `ps` executable, usually provided by `procps` or a similar package. +- [XZ Utils](http://tukaani.org/xz/) 4.9 or higher +- a [properly mounted]( + https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount) + `cgroupfs` hierarchy; a single, all-encompassing `cgroup` mount + point is not sufficient. See Github issues + [#2683](https://github.com/docker/docker/issues/2683), + [#3485](https://github.com/docker/docker/issues/3485), + [#4568](https://github.com/docker/docker/issues/4568)). -A 3.10 Linux kernel is the minimum requirement for Docker. -Kernels older than 3.10 lack some of the features required to run Docker -containers. These older versions are known to have bugs which cause data loss -and frequently panic under certain conditions. +#### Enable AppArmor and SELinux when possible -The latest minor version (3.x.y) of the 3.10 (or a newer maintained version) -Linux kernel is recommended. Keeping the kernel up to date with the latest -minor version will ensure critical kernel bugs get fixed. - -> **Warning**: -> Installing custom kernels and kernel packages is probably not -> supported by your Linux distribution's vendor. Please make sure to -> ask your vendor about Docker support first before attempting to -> install custom kernels on your distribution. - -> **Warning**: -> Installing a newer kernel might not be enough for some distributions -> which provide packages which are too old or incompatible with -> newer kernels. - -Note that Docker also has a client mode, which can run on virtually any -Linux kernel (it even builds on macOS!). - -## Enable AppArmor and SELinux when possible - -Please use AppArmor or SELinux if your Linux distribution supports +It is recommended to use AppArmor or SELinux if your Linux distribution supports either of the two. This helps improve security and blocks certain -types of exploits. Your distribution's documentation should provide -detailed steps on how to enable the recommended security mechanism. - -Some Linux distributions enable AppArmor or SELinux by default and -they run a kernel which doesn't meet the minimum requirements (3.10 -or newer). Updating the kernel to 3.10 or newer on such a system -might not be enough to start Docker and run containers. -Incompatibilities between the version of AppArmor/SELinux user -space utilities provided by the system and the kernel could prevent -Docker from running, from starting containers or, cause containers to -exhibit unexpected behaviour. +types of exploits. Review the documentation for your Linux distribution for +instructions for enabling and configuring AppArmor or SELinux. > **Warning**: -> If either of the security mechanisms is enabled, it should not be -> disabled to make Docker or its containers run. This will reduce -> security in that environment, lose support from the distribution's -> vendor for the system, and might break regulations and security -> policies in heavily regulated environments. +> If either of the security mechanisms is enabled, do not disable it as a +> work-around to make Docker or its containers run. Instead, configure it +> correctly to fix any problems. -## Get the Docker Engine binaries +### Install static binaries -You can download either the latest release binaries or a specific version. View -the `docker/docker` [Releases page](https://github.com/docker/docker/releases). +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/docker/docker/releases) for the version + of Docker you want to install. You can choose a `tar.gz` archive or `zip` + archive. -A group of download links is included at the bottom of the release notes for -each version of Docker. You can use these links to download the source code -archive for that release, binaries for supported platforms, and static binaries -for unsupported Linux platforms. Use the links listed in the Downloads section -to download the appropriate binaries. +2. Extract the archive using `tar` or `unzip`, depending on the format you + downloaded. The `dockerd` and `docker` binaries are extracted. -### Limitations of Windows and macOS binaries + ```bash + $ tar xzvf /path/to/.tar.gz + ``` -For Windows, the `i386` download contains a 32-bit client-only binary. The -`x86_64` download contains both client and daemon binaries for 64-bit Windows -Server 2016 and Windows 10 systems. + ```bash + $ unzip /path/to/.zip + ``` -The macOS binary only contains a client. You cannot use it to run the `dockerd` -daemon. If you need to run the daemon, install -[Docker for Mac](/docker-for-mac/index.md) instead. +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. -### URL patterns for static binaries + ```bash + $ sudo cp docker/* /usr/bin/ + ``` -The URLs for released binaries are stable and follow a predictable pattern. -Unfortunately, it is not possible to browse the releases in a directory -structure. If you do not want to get the links from the release notes for a -release, you can infer the URL for the binaries by using the following patterns: +4. Start the Docker daemon: -| Description | URL pattern | -|------------------------|-------------------------------------------------------------------| -| Latest Linux 64-bit | `https://get.docker.com/builds/Linux/x86_64/docker-latest.tgz` | -| Latest Linux 32-bit | `https://get.docker.com/builds/Linux/i386/docker-latest.tgz` | -| Specific version Linux 64-bit| `https://get.docker.com/builds/Linux/x86_64/docker-.tgz` | -| Specific version Linux 32-bit| `https://get.docker.com/builds/Linux/i386/docker-.tgz` | -| Latest Windows 64-bit | `https://get.docker.com/builds/Windows/x86_64/docker-latest.zip` | -| Latest Windows 32-bit | `https://get.docker.com/builds/Windows/i386/docker-latest.zip` | -| Specific version Windows 64-bit | `https://get.docker.com/builds/Windows/x86_64/docker-.zip` | -| Specific version Windows 32-bit | `https://get.docker.com/builds/Windows/i386/docker-.zip` | -| Latest MacOS 64-bit | `https://get.docker.com/builds/Darwin/x86_64/docker-latest.tgz` | -| Specific version MacOS 64-bit | `https://get.docker.com/builds/Darwin/x86_64/docker-.tgz` | + ```bash + $ sudo dockerd & + ``` -For example, the stable URL for the Docker 1.11.0 64-bit static binary for Linux -is `https://get.docker.com/builds/Linux/x86_64/docker-1.11.0.tgz`. + If you need to start the daemon with additional options, modify the above + command accordingly. +>>>>>>> c02c644... Rewrite and reorganize Linux install instructions -> **Note** These instructions are for Docker Engine 1.11 and up. Engine 1.10 and -> under consists of a single binary, and instructions for those versions are -> different. To install version 1.10 or below, follow the instructions in the -> [1.10 documentation](/v1.10/engine/installation/binaries/){: target="_blank" class="_" }. +5. Verify that Docker is installed correctly by running the `hello-world` + image. -To verify the integrity of downloaded files, you can get an MD5 or SHA256 -checksum by adding `.md5` or `.sha256` to the end of the URL. For instance, -to verify the `docker-1.11.0.tgz` link above, use the URL -`https://get.docker.com/builds/Linux/x86_64/docker-1.11.0.tgz.md5` or -`https://get.docker.com/builds/Linux/x86_64/docker-1.11.0.tgz.sha256`. + ```bash + $ sudo docker run hello-world + ``` -## Install the Linux binaries + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. -After downloading, you extract the archive, which puts the binaries in a -directory named `docker` in your current location. +### Next steps -```bash -$ tar -xvzf docker-latest.tgz +- Continue to [Post-installation steps for Linux](linux-postinstall.md) -docker/ -docker/docker -docker/docker-containerd -docker/docker-containerd-ctr -docker/docker-containerd-shim -docker/docker-proxy -docker/docker-runc -docker/dockerd -``` +- Continue with the [User Guide](../../userguide/index.md). -Engine requires these binaries to be installed in your host's `$PATH`. -For example, to install the binaries in `/usr/bin`: +## Install client binaries on macOS -```bash -$ mv docker/* /usr/bin/ -``` +The macOS binary includes the Docker client only. It does not include the +`dockerd` daemon. -> **Note**: Depending on your current setup, you can specify custom paths -> for some of the binaries provided. +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/docker/docker/releases) for the version + of Docker you want to install. You can choose a `tar.gz` archive or + `zip` archive. -> **Note**: If you already have Engine installed on your host, make sure you -> stop Engine before installing (`killall docker`), and install the binaries -> in the same location. You can find the location of the current installation -> with `dirname $(which docker)`. +2. Extract the archive using `tar` or `unzip`, depending on the format you + downloaded. The `docker` binary is extracted. -### Run the Engine daemon on Linux + ```bash + $ tar xzvf /path/to/.tar.gz + ``` -You can manually start the Engine in daemon mode using: + ```bash + $ unzip /path/to/.zip + ``` +3. **Optional**: Move the binaries 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. -```bash -$ sudo dockerd & -``` + ```bash + $ sudo cp docker/docker /usr/local/bin/ + ``` -The GitHub repository provides samples of init-scripts you can use to control -the daemon through a process manager, such as upstart or systemd. You can find -these scripts in the -contrib directory. +4. To connect the `docker` client to a remote host, either set the + `DOCKER_HOST` environment variable to the hostname or IP address of the + Docker daemon or add the `-H ` option to each `docker` command. -For additional information about running the Engine in daemon mode, refer to -the [daemon command](../reference/commandline/dockerd.md) in the Engine command -line reference. +5. Verify that Docker is installed correctly by running the `hello-world` + image. -## Install the macOS binaries + ```bash + $ sudo docker -H run hello-world + ``` -You can extract the downloaded archive either by double-clicking the downloaded -`.tgz` or on the command line, using `tar -xvzf docker-1.11.0.tgz`. You can run -the client binary from any location on your filesystem. + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. -## Install the Windows binary -You can extract the downloaded archive by double-clicking the downloaded -`.zip`. You can run the client binary from any location on your filesystem. +## Install server and binaries on Windows -## Run client commands without root access +You can install Docker from binaries on Windows Server 2016 or Windows 10. -On Linux, the `dockerd` daemon always runs as the root user and binds to a Unix -socket instead of a TCP port. By default that Unix socket is owned by the -`root` user. This means that by default, you need to use `sudo` to run `docker` -commands. +- To install both client and server binaries, download the 64-bit binary. The + archive includes `x86.64` in the file name. -If you (or your Docker installer) create a Unix group called `docker` and add -users to it, the `dockerd` daemon will change the ownership of the Unix socket -to be readable and writable by members of the `docker` group when the daemon -starts. The `dockerd` daemon must always run as the root user, but you can run -`docker` client commands, such as `docker run`, as a non-privileged user. +- To install the client only, download the 32-bit binary. The archive includes + `i386` in the file name. -> **Warning**: -> Membership in the *docker* group (or the group specified with `-G`) is equivalent -> to `root` access. See -> [*Docker Daemon Attack Surface*](../security/security.md#docker-daemon-attack-surface) details. -## Upgrade Docker Engine +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/docker/docker/releases) for the version + of Docker you want to install. -Before you upgrade your manual installation of Docker Engine on Linux, first -stop the docker daemon: +2. Extract the archive using OS utilities. A `docker` directory is created, + and contains a `docker.exe` binary and a `dockerd.exe` binary if you + downloaded the 64-bit version. -```bash -$ killall dockerd -``` -After the Docker daemon stops, move the old binaries out of the way and follow -the [regular installation steps](binaries.md#get-the-linux-binaries). +3. **Optional**: Move the binaries to a directory on your executable path. If + you skip this step, you must provide the path to the + executable when you invoke `docker` or `dockerd` commands. + +4. If you downloaded the 64-bit archive, you can start the `dockerd` daemon. + + ```none + C:\> dockerd + ``` + +5. Verify that Docker is installed correctly by running the `hello-world` + image. + + > **Note**: To connect the `docker` client to a remote host, either set the + > `DOCKER_HOST` environment variable to the hostname or IP address of the + > Docker daemon or add the `-H ` option to each `docker` command. + + ```none + C:\> docker run hello-world + ``` + + 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. ## Next steps diff --git a/engine/installation/index.md b/engine/installation/index.md index ea4ffa569d..fc9c876dfe 100644 --- a/engine/installation/index.md +++ b/engine/installation/index.md @@ -12,22 +12,18 @@ Docker Engine is supported on Linux, Cloud, Windows, and macOS. Installation instructions are available for the following: ## On Linux -* [Arch Linux](linux/archlinux.md) * [CentOS](linux/centos.md) -* [CRUX Linux](linux/cruxlinux.md) * [Debian](linux/debian.md) * [Fedora](linux/fedora.md) -* [Gentoo](linux/gentoolinux.md) * [Oracle Linux](linux/oracle.md) -* [Raspbian](linux/raspbian.md) * [Red Hat Enterprise Linux](linux/rhel.md) * [openSUSE and SUSE Linux Enterprise](linux/SUSE.md) * [Ubuntu](linux/ubuntulinux.md) +* [Other Linux distributions](linux/other.md) If your linux distribution is not listed above, don't give up yet. To try out -Docker on a distribution that is not listed above, go here: -[Installation from binaries](binaries.md). - +Docker on a different Linux distribution, consider +[installing from binaries](binaries.md). ## On macOS and Windows diff --git a/engine/installation/linux/SUSE.md b/engine/installation/linux/SUSE.md index 96c7cbfca7..6723125664 100644 --- a/engine/installation/linux/SUSE.md +++ b/engine/installation/linux/SUSE.md @@ -1,112 +1,301 @@ --- -description: Installation instructions for Docker on openSUSE and on SUSE Linux Enterprise. -keywords: openSUSE, SUSE Linux Enterprise, SUSE, SLE, docker, documentation, installation +description: Instructions for installing Docker on OpenSUSE and SLES +keywords: Docker, Docker documentation, requirements, apt, installation, suse, opensuse, sles, rpm, install, uninstall, upgrade, update redirect_from: - /engine/installation/SUSE/ -title: Install Docker on openSUSE and SUSE Linux Enterprise +title: Get Docker for OpenSUSE and SLES --- -This page provides instructions for installing and configuring the latest -Docker Engine software on openSUSE and SUSE systems. - ->**Note:** You can also find bleeding edge Docker versions inside of the repositories maintained by the [Virtualization:containers project](https://build.opensuse.org/project/show/Virtualization:containers) on the [Open Build Service](https://build.opensuse.org/). This project delivers also other packages that are related with the Docker ecosystem (for example, Docker Compose). +To get started with Docker on OpenSUSE or SLES, make sure you +[meet the prerequisites](#prerequisites), then +[install Docker](#install-docker). ## Prerequisites -You must be running a 64 bit architecture. +### OS requirements -## openSUSE +To install Docker, you need the 64-bit version one of the following: -Docker is part of the official openSUSE repositories starting from 13.2. No -additional repository is required on your system. +- OpenSuSE Leap 42.x +- SLES 12.x -## SUSE Linux Enterprise +### Remove unofficial Docker packages -Docker is officially supported on SUSE Linux Enterprise 12 and later. You can find the latest supported Docker packages inside the `Container` module. To enable this module, do the following: +OpenSUSE's operating system repositories contain an older version of Docker, +with the package name `docker` instead of `docker-engine`. If you installed this +version of Docker on OpenSUSE or on SLES by using the OpenSUSE repositories, +remove it using the following command: -1. Start YaST, and select *Software > Software Repositories*. -2. Click *Add* to open the add-on dialog. -3. Select *Extensions and Module from Registration Server* and click *Next*. -4. From the list of available extensions and modules, select *Container Module* and click *Next*. - The containers module and its repositories are added to your system. -5. If you use Subscription Management Tool, update the list of repositories at the SMT server. +```bash +$ sudo zypper rm docker +``` -Otherwise execute the following command: +The contents of `/var/lib/docker` are not removed, so any images, containers, +or volumes you created using the older version of Docker are preserved. - $ sudo SUSEConnect -p sle-module-containers/12/x86_64 -r '' +## Install Docker -> **Note:** currently the `-r ''` flag is required to avoid a known limitation of `SUSEConnect`. +You can install Docker in different ways, depending on your needs: -The [Virtualization:containers project](https://build.opensuse.org/project/show/Virtualization:containers) -on the [Open Build Service](https://build.opensuse.org/) contains also bleeding -edge Docker packages for SUSE Linux Enterprise. However these packages are -**not supported** by SUSE. +- Most users + [set up Docker's repositories](#install-using-the-repository) and install + from them, for ease of installation and upgrade tasks. This is the + recommended approach. -### Install Docker +- Some users download the RPM package and install it manually and manage + upgrades completely manually. -1. Install the Docker package: +- 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 + follow these procedures. - $ sudo zypper in docker +### Install using the repository -2. Start the Docker daemon. +Before you install Docker for the first time on a new host machine, you need to +set up the Docker repository. Afterward, you can install, update, or downgrade +Docker from the repository. - $ sudo systemctl start docker +#### Set up the repository -3. Test the Docker installation. +1. Verify and import Docker's public key, which is used to sign packages in + Docker's repository. - $ sudo docker run hello-world + First, verify that the fingerprint is `58118E89F3A912897C070ADBF76221572C52609D`: -## Configure Docker boot options + ```bash + $ curl -s https://yum.dockerproject.org/gpg | gpg --quiet --with-fingerprint -You can use these steps on openSUSE or SUSE Linux Enterprise. To start the `docker daemon` at boot, set the following: + pub 4096R/2C52609D 2015-07-14 + Key fingerprint = 5811 8E89 F3A9 1289 7C07 0ADB F762 2157 2C52 609D + uid Docker Release Tool (releasedocker) + ``` - $ sudo systemctl enable docker + If the fingerprint matches, import the key: -The `docker` package creates a new group named `docker`. Users, other than -`root` user, must be part of this group to interact with the -Docker daemon. You can add users with this command syntax: + ```bash + $ sudo rpm --import https://yum.dockerproject.org/gpg + ``` - $ sudo /usr/sbin/usermod -a -G docker +2. Use the following command to set up the **stable** repository: -Once you add a user, make sure they relog to pick up these new permissions. + ```bash + $ sudo zypper addrepo \ + https://yum.dockerproject.org/repo/main/opensuse/13.2/ \ + docker-main + ``` -## Enable external network access +3. **Optional**: Enable the **testing** repository. You can enable it alongside + the stable repository. Do not use unstable repositories on on production + systems or for non-testing workloads. -If you want your containers to be able to access the external network, you must -enable the `net.ipv4.ip_forward` rule. To do this, use YaST. + > **Warning**: If you have both stable and unstable repositories enabled, + > updating without specifying a version in the `zypper install` or + > `zypper update` command will always install the highest possible version, + > which will almost certainly be an unstable one. -For openSUSE Tumbleweed and later, browse to the **System -> Network Settings -> Routing** menu. For SUSE Linux Enterprise 12 and previous openSUSE versions, browse to **Network Devices -> Network Settings -> Routing** menu (f) and check the *Enable IPv4 Forwarding* box. -When networking is handled by the Network Manager, instead of YaST you must edit -the `/etc/sysconfig/SuSEfirewall2` file needs by hand to ensure the `FW_ROUTE` -flag is set to `yes` like so: + ```bash + $ sudo zypper addrepo \ + https://yum.dockerproject.org/repo/testing/opensuse/13.2/ \ + docker-testing + ``` - FW_ROUTE="yes" + You can disable a repository at any time by running the `zypper rmrepo` + command. The following command disables the `testing` repository. -## Custom daemon options + ```bash + $ sudo zypper removerepo docker-testing + ``` -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read the systemd article to -learn how to [customize your systemd Docker daemon options](../../admin/systemd.md). +#### Install Docker -## Uninstallation +1. Update the `zypper` package index. -To uninstall the Docker package: + ```bash + $ sudo zypper refresh + ``` - $ sudo zypper rm docker +2. Install the latest version of Docker, or go to the next step to install a + specific version. -The above command does not remove images, containers, volumes, or user created -configuration files on your host. If you wish to delete all images, containers, -and volumes run the following command: + ```bash + $ sudo zypper install docker-engine + ``` - $ rm -rf /var/lib/docker + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating Docker without specifying a version in the + > `zypper install` or `zypper update` command will always install the highest + > available version, which will almost certainly be an unstable one. -You must delete the user created configuration files manually. + The RPM will install, but you will receive the following error during the + post-installation procedure, because Docker cannot start the service + automatically: -## Where to go from here + ```none + Additional rpm output: + /var/tmp/rpm-tmp.YGySzA: line 1: fg: no job control + ``` -You can find more details about Docker on openSUSE or SUSE Linux Enterprise in the -[Docker quick start guide](https://www.suse.com/documentation/sles-12/dockerquick/data/dockerquick.html) -on the SUSE website. The document targets SUSE Linux Enterprise, but its contents apply also to openSUSE. + Start Docker: -Continue to the [User Guide](../../userguide/index.md). + ```bash + $ sudo service docker start + ``` + +3. On production systems, you should install a specific version of Docker + instead of always using the latest. List the available versions. The + following example only lists binary packages and is truncated. To also list + source packages, omit the `-t package` flag from the command. + + ```bash + $ zypper search -s --match-exact -t package docker-engine + + Loading repository data... + Reading installed packages... + + S | Name | Type | Version | Arch | Repository + --+---------------+---------+---------------------------------------+--------+--------------- + | docker-engine | package | 1.13.0-1 | x86_64 | docker-main + | docker-engine | package | 1.13.0-0.7.rc7 | x86_64 | docker-testing + | docker-engine | package | 1.13.0-0.6.rc6 | x86_64 | docker-testing + | docker-engine | package | 1.13.0-0.5.rc5 | x86_64 | docker-testing + | docker-engine | package | 1.13.0-0.4.rc4 | x86_64 | docker-testing + | docker-engine | package | 1.13.0-0.3.rc3 | x86_64 | docker-testing + | docker-engine | package | 1.13.0-0.2.rc2 | x86_64 | docker-testing + | docker-engine | package | 1.13.0-0.1.rc1 | x86_64 | docker-testing + | docker-engine | package | 1.12.6-1 | x86_64 | docker-main + | docker-engine | package | 1.12.5-1 | x86_64 | docker-main + | docker-engine | package | 1.12.4-1 | x86_64 | docker-main + | docker-engine | package | 1.12.3-1 | x86_64 | docker-main + | docker-engine | package | 1.12.2-1 | x86_64 | docker-main + | docker-engine | package | 1.12.1-1 | x86_64 | docker-main + | docker-engine | package | 1.12.0-1 | x86_64 | docker-main + ``` + + The contents of the list depend upon which repositories you have enabled. + Choose a specific version to + install. The third column is the version string. The fifth column is the + repository name, which indicates which repository the package is from and by + extension its stability level. To install a specific version, append the + version string to the package name and separate them by a hyphen (`-`): + + ```bash + $ sudo zypper install docker-engine- + ``` + + The RPM will install, but you will receive the following error during the + post-installation procedure, because Docker cannot start the service + automatically: + + ```none + Additional rpm output: + /var/tmp/rpm-tmp.YGySzA: line 1: fg: no job control + ``` + + Start Docker: + + ```bash + $ sudo service docker start + ``` + +4. Verify that `docker` is installed correctly by running the `hello-world` + image. + + ```bash + $ sudo docker run hello-world + ``` + + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Linux postinstall](linux-postinstall.md) to allow non-privileged +users to run Docker commands and for other optional configuration steps. + +#### Upgrade Docker + +To upgrade Docker, first run `sudo zypper refresh`, then follow the +[installation instructions](#install-docker), choosing the new version you want +to install. + +### Install from a package + +If you cannot use Docker's repository to install Docker, you can download the +`.rpm` file for your release and install it manually. You will need to download +a new file each time you want to upgrade Docker. + +1. Go to [https://yum.dockerproject.org/repo/main/opensuse/13.2/Packages/](https://yum.dockerproject.org/repo/main/opensuse/13.2/Packages/) + and download the `.rpm` file for the Docker version you want to install. + + > **Note**: To install a testing version, change the word `main` in the + > URL to `testing`. Do not use unstable versions of Docker in production + > or for non-testing workloads. + +2. Install Docker, changing the path below to the path where you downloaded + the Docker package. + + ```bash + $ sudo yum -y install /path/to/package.rpm + ``` + + The RPM will install, but you will receive the following error during the + post-installation procedure, because Docker cannot start the service + automatically: + + ```none + Additional rpm output: + /var/tmp/rpm-tmp.YGySzA: line 1: fg: no job control + ``` + + Start Docker: + + ```bash + $ sudo service docker start + ``` + +3. Verify that `docker` is installed correctly by running the `hello-world` + image. + + ```bash + $ sudo docker run hello-world + ``` + + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Post-installation steps for Linux](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. + +#### Upgrade Docker + +To upgrade Docker, download the newer package file and repeat the +[installation procedure](#install-from-a-package), using `zypper update` +instead of `zypper install`, and pointing to the new file. + +## Uninstall Docker + +1. Uninstallation using `zypper rm` fails. Uninstall the Docker package using + the following command: + + ```bash + $ sudo rpm -e --noscripts docker-engine + ``` + +2. Images, containers, volumes, or customized configuration files on your host + are not automatically removed. To delete all images, containers, and + volumes: + + ```bash + $ sudo rm -rf /var/lib/docker + ``` + +You must delete any edited configuration files manually. + +## Next steps + +- Continue to [Post-installation steps for Linux](linux-postinstall.md) + +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/centos.md b/engine/installation/linux/centos.md index bea52f2b5c..40436e556d 100644 --- a/engine/installation/linux/centos.md +++ b/engine/installation/linux/centos.md @@ -1,234 +1,234 @@ --- description: Instructions for installing Docker on CentOS -keywords: Docker, Docker documentation, requirements, linux, centos, epel, docker.io, docker-io +keywords: Docker, Docker documentation, requirements, apt, installation, centos, rpm, install, uninstall, upgrade, update redirect_from: - /engine/installation/centos/ -title: Install Docker on CentOS +title: Get Docker for CentOS --- -Docker runs on CentOS 7.X. An installation on other binary compatible EL7 -distributions such as Scientific Linux might succeed, but Docker does not test -or support Docker on these distributions. - -These instructions install Docker using release packages and installation -mechanisms managed by Docker, to be sure that you get the latest version -of Docker. If you wish to install using CentOS-managed packages, consult -your CentOS release documentation. +To get started with Docker on CentOS, make sure you +[meet the prerequisites](#prerequisites), then +[install Docker](#install-docker). ## Prerequisites -Docker requires a 64-bit OS and version 3.10 or higher of the Linux kernel. +### OS requirements -To check your current kernel version, open a terminal and use `uname -r` to -display your kernel version: +To install Docker, you need the 64-bit version of CentOS 7. + +### Remove unofficial Docker packages + +Red Hat's operating system repositories contain an older version of Docker, with +the package name `docker` instead of `docker-engine`. If you installed this +version of Docker, remove it using the following command: ```bash -$ uname -r -3.10.0-229.el7.x86_64 +$ sudo yum -y remove docker ``` -Finally, it is recommended that you fully update your system. Keep in mind -that your system should be fully patched to fix any potential kernel bugs. -Any reported kernel bugs may have already been fixed on the latest kernel -packages. +The contents of `/var/lib/docker` are not removed, so any images, containers, +or volumes you created using the older version of Docker are preserved. -## Install Docker Engine +## Install Docker -There are two ways to install Docker Engine. You can [install using the `yum` -package manager](#install-with-yum). Or you can use `curl` with the [`get.docker.com` -site](#install-with-the-script). This second method runs an installation script -which also installs via the `yum` package manager. +You can install Docker in different ways, depending on your needs: -### Install with yum +- Most users + [set up Docker's repositories](#install-using-the-repository) and install + from them, for ease of installation and upgrade tasks. This is the + recommended approach. -1. Log into your machine as a user with `sudo` or `root` privileges. +- Some users download the RPM package and install it manually and manage + upgrades completely manually. -2. Make sure your existing packages are up-to-date. +- Some users cannot use third-party repositories, and must rely on the version + of Docker in the CentOS repositories. This version of Docker may be out of + date. Those users should consult the CentOS documentation and not follow these + procedures. + +### Install using the repository + +Before you install Docker for the first time on a new host machine, you need to +set up the Docker repository. Afterward, you can install, update, or downgrade +Docker from the repository. + +#### Set up the repository + +1. Use the following command to set up the **stable** repository: ```bash - $ sudo yum update + $ sudo yum-config-manager \ + --add-repo \ + https://docs.docker.com/engine/installation/linux/repo_files/centos/docker.repo ``` -3. Add the `yum` repo. +2. **Optional**: Enable the **testing** repository. This repository is included + in the `docker.repo` file above but is disabled by default. You can enable + it alongside the stable repository. Do not use unstable repositories on + on production systems or for non-testing workloads. - ```none - $ sudo tee /etc/yum.repos.d/docker.repo <<-'EOF' - [dockerrepo] - name=Docker Repository - baseurl=https://yum.dockerproject.org/repo/main/centos/7/ - enabled=1 - gpgcheck=1 - gpgkey=https://yum.dockerproject.org/gpg - EOF - ``` - -4. Install the Docker package. + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating without specifying a version in the `yum install` + > or `yum update` command will always install the highest possible version, + > which will almost certainly be an unstable one. ```bash - $ sudo yum install docker-engine + $ sudo yum-config-manager --set-enabled docker-testing ``` -5. Enable the service. + You can disable the `testing` repository by running the `yum-config-manager` + command with the `--set-disabled` flag. To re-enable it, use the + `--set-enabled` flag. The following command disables the `testing` + repository. ```bash - $ sudo systemctl enable docker.service + $ sudo yum-config-manager --set-disabled docker-testing ``` -6. Start the Docker daemon. +#### Install Docker + +1. Update the `yum` package index. ```bash - $ sudo systemctl start docker + $ sudo yum -y check-update ``` -7. Verify `docker` is installed correctly by running a test image in a container. - - $ sudo docker run --rm hello-world - - Unable to find image 'hello-world:latest' locally - latest: Pulling from library/hello-world - c04b14da8d14: Pull complete - Digest: sha256:0256e8a36e2070f7bf2d0b0763dbabdd67798512411de4cdcf9431a1feb60fd9 - Status: Downloaded newer image for hello-world:latest - - Hello from Docker! - This message shows that your installation appears to be working correctly. - - To generate this message, Docker took the following steps: - 1. The Docker client contacted the Docker daemon. - 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. - 3. The Docker daemon created a new container from that image which runs the - executable that produces the output you are currently reading. - 4. The Docker daemon streamed that output to the Docker client, which sent it - to your terminal. - - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash - - Share images, automate workflows, and more with a free Docker Hub account: - https://hub.docker.com - - For more examples and ideas, visit: - https://docs.docker.com/engine/userguide/ - -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read our Systemd article to -learn how to [customize your Systemd Docker daemon options](../../admin/systemd.md). - -### Install with the script - -1. Log into your machine as a user with `sudo` or `root` privileges. - -2. Make sure your existing packages are up-to-date. +2. Install the latest version of Docker, or go to the next step to install a + specific version. ```bash - $ sudo yum update + $ sudo yum -y install docker-engine ``` -3. Run the Docker installation script. + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating Docker without specifying a version in the + > `yum install` or `yum upgrade` command will always install the highest + > available version, which will almost certainly be an unstable one. + +3. On production systems, you should install a specific version of Docker + instead of always using the latest. List the available versions. This + example uses the `sort -r` command to sort the results by version number, + highest to lowest. + + > **Note**: This `yum list` command only shows binary packages. To show + > source packages as well, omit the `.x86_64` from the package name. ```bash - $ curl -fsSL https://get.docker.com/ | sh + $ yum list docker-engine.x86_64 --showduplicates |sort -r + + docker-engine.x86_64 1.13.0-1.el7 docker-main + docker-engine.x86_64 1.13.0-0.5.rc5.el7 docker-testing + docker-engine.x86_64 1.13.0-0.4.rc4.el7 docker-testing + docker-engine.x86_64 1.13.0-0.3.rc3.el7 docker-testing + docker-engine.x86_64 1.13.0-0.2.rc2.el7 docker-testing + docker-engine.x86_64 1.13.0-0.1.rc1.el7 docker-testing + docker-engine.x86_64 1.12.5-1.el7 docker-main + docker-engine.x86_64 1.12.4-1.el7 docker-main + docker-engine.x86_64 1.12.3-1.el7 docker-main + docker-engine.x86_64 1.12.2-1.el7 docker-main + docker-engine.x86_64 1.12.1-1.el7 docker-main + docker-engine.x86_64 1.12.0-1.el7 docker-main ``` - This script adds the `docker.repo` repository and installs Docker. - -4. Enable the service. + The contents of the list depend upon which repositories are enabled, and + will be specific to your version of CentOS (indicated by the `.el7` suffix + on the version, in this example). Choose a specific version to install. The + second column is the version string. The third column is the repository + name, which indicates which repository the package is from and by extension + its stability level. To install a specific version, append the version + string to the package name and separate them by a hyphen (`-`): ```bash - $ sudo systemctl enable docker.service + $ sudo yum -y install docker-engine- ``` -5. Start the Docker daemon. + The Docker daemon starts automatically. + +4. Verify that `docker` is installed correctly by running the `hello-world` + image. ```bash - $ sudo systemctl start docker + $ sudo docker run hello-world ``` -6. Verify `docker` is installed correctly by running a test image in a container. + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Linux postinstall](linux-postinstall.md) to allow non-privileged +users to run Docker commands and for other optional configuration steps. + +#### Upgrade Docker + +To upgrade Docker, first run `sudo dnf check-update`, then follow the +[installation instructions](#install-docker), choosing the new version you want +to install. + +### Install from a package + +If you cannot use Docker's repository to install Docker, you can download the +`.rpm` file for your release and install it manually. You will need to download +a new file each time you want to upgrade Docker. + +1. Go to [https://yum.dockerproject.org/repo/main/centos/](https://yum.dockerproject.org/repo/main/centos/) + and choose the subdirectory for your CentOS version. Download the `.rpm` file + for the Docker version you want to install. + + > **Note**: To install a testing version, change the word `stable` in the + > URL to `testing`. Do not use unstable versions of Docker in production + > or for non-testing workloads. + +2. Install Docker, changing the path below to the path where you downloaded + the Docker package. ```bash - $ sudo docker run --rm hello-world + $ sudo yum -y install /path/to/package.rpm ``` -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read our Systemd article to -learn how to [customize your Systemd Docker daemon options](../../admin/systemd.md). + The Docker daemon starts automatically. -## Create a docker group - -The `docker` daemon binds to a Unix socket instead of a TCP port. By default -that Unix socket is owned by the user `root` and other users can access it with -`sudo`. For this reason, `docker` daemon always runs as the `root` user. - -To avoid having to use `sudo` when you use the `docker` command, create a Unix -group called `docker` and add users to it. When the `docker` daemon starts, it -makes the ownership of the Unix socket read/writable by the `docker` group. - ->**Warning**: The `docker` group is equivalent to the `root` user; For details ->on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../../security/security.md#docker-daemon-attack-surface) for details. - -To create the `docker` group and add your user: - -1. Log into your machine as a user with `sudo` or `root` privileges. - -2. Create the `docker` group. +3. Verify that `docker` is installed correctly by running the `hello-world` + image. ```bash - $ sudo groupadd docker + $ sudo docker run hello-world ``` -3. Add your user to `docker` group. + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Post-installation steps for Linux](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. + +#### Upgrade Docker + +To upgrade Docker, 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. + + +## Uninstall Docker + +1. Uninstall the Docker package: ```bash - $ sudo usermod -aG docker your_username + $ sudo yum -y remove docker-engine ``` -4. Log out and log back in. - - This ensures your user is running with the correct permissions. - -5. Verify that your user is in the docker group by running `docker` without `sudo`. +2. Images, containers, volumes, or customized configuration files on your host + are not automatically removed. To delete all images, containers, and + volumes: ```bash - $ docker run --rm hello-world + $ sudo rm -rf /var/lib/docker ``` -## Start the docker daemon at boot +You must delete any edited configuration files manually. -Configure the Docker daemon to start automatically when the host starts: +## Next steps -```bash -$ sudo systemctl enable docker -``` +- Continue to [Post-installation steps for Linux](linux-postinstall.md) -## Uninstall - -You can uninstall the Docker software with `yum`. - -1. List the installed Docker packages. - - ```bash - $ yum list installed | grep docker - - docker-engine.x86_64 1.12.3-1.el7.centos @dockerrepo - docker-engine-selinux.noarch 1.12.3-1.el7.centos @dockerrepo - ``` - -2. Remove the package. - - ```bash - $ sudo yum -y remove docker-engine.x86_64 - $ sudo yum -y remove docker-engine-selinux.noarch - ``` - - This command does not remove images, containers, volumes, or user-created - configuration files on your host. - -3. To delete all images, containers, and volumes, run the following command: - - ```bash - $ rm -rf /var/lib/docker - ``` - -4. Locate and delete any user-created configuration files. +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/debian.md b/engine/installation/linux/debian.md index acba6693fe..c7eb5fb6bc 100644 --- a/engine/installation/linux/debian.md +++ b/engine/installation/linux/debian.md @@ -1,200 +1,261 @@ --- -description: Instructions for installing Docker on Debian. -keywords: Docker, Docker documentation, installation, debian +description: Instructions for installing Docker on Debian +keywords: Docker, Docker documentation, requirements, apt, installation, debian, install, uninstall, upgrade, update redirect_from: - /engine/installation/debian/ -title: Install Docker on Debian +title: Get Docker for Debian --- -Docker is supported on the following versions of Debian: - - - Debian testing stretch - - Debian 8.0 Jessie - - Debian 7.7 Wheezy (backports required) - - >**Note**: If you previously installed Docker using `APT`, make sure you update - your `APT` sources to the new `APT` repository. +To get started with Docker on Debian, make sure you +[meet the prerequisites](#prerequisites), then +[install Docker](#install-docker). ## Prerequisites - Docker requires a 64-bit installation regardless of your Debian version. - Additionally, your kernel must be 3.10 at minimum. The latest 3.10 minor - version or a newer maintained version are also acceptable. +### OS requirements - Kernels older than 3.10 lack some of the features required to run Docker - containers. These older versions are known to have bugs which cause data loss - and frequently panic under certain conditions. +To install Docker, you need the 64-bit version of one of these Debian versions: - To check your current kernel version, open a terminal and use `uname -r` to - display your kernel version: +- Stretch (testing) +- Jessie 8.0 (LTS) +- Wheezy 7.7 (LTS) - $ uname -r +#### Extra steps for Wheezy 7.7 - Additionally, for users of Debian Wheezy, backports must be available. To enable backports in Wheezy: +- You need at least version 3.10 of the Linux kernel. Debian Wheezy ships with + version 3.2, so you may need to + [update the kernel](https://wiki.debian.org/HowToUpgradeKernel){: target="_blank" class="_" }. + To check your kernel version: - 1. Log into your machine and open a terminal with `sudo` or `root` privileges. + ```bash + $ uname -r + ``` - 2. Open the `/etc/apt/sources.list.d/backports.list` file in your favorite editor. +- Enable the `backports` repository. See the + [Debian documentation](https://backports.debian.org/Instructions/){: target="_blank" class"_"}. - If the file doesn't exist, create it. +### Recommended extra packages - 3. Remove any existing entries. +You need `curl` if you don't have it. Unless you have a strong reason not to, +install the `linux-image-extra-*` packages, which allow Docker to use the `aufs` +storage drivers. **This applies to all versions of Debian**. - 4. Add an entry for backports on Debian Wheezy. +```bash +$ sudo apt-get update - An example entry: - - deb http://http.debian.net/debian wheezy-backports main - - 5. Update package information: - - $ apt-get update - -### Update your apt repository - -Docker's `APT` repository contains Docker 1.7.1 and higher. To set `APT` to use -from the new repository: - - 1. If you haven't already done so, log into your machine as a user with `sudo` or `root` privileges. - - 2. Open a terminal window. - - 3. Purge any older repositories. - - $ sudo apt-get purge "lxc-docker*" - $ sudo apt-get purge "docker.io*" - - 4. Update package information, ensure that APT works with the `https` method, and that CA certificates are installed. - - $ sudo apt-get update - $ sudo apt-get install apt-transport-https ca-certificates gnupg2 - - 5. Add the new `GPG` key. - - $ sudo apt-key adv \ - --keyserver hkp://ha.pool.sks-keyservers.net:80 \ - --recv-keys 58118E89F3A912897C070ADBF76221572C52609D - - 6. Open the `/etc/apt/sources.list.d/docker.list` file in your favorite editor. - - If the file doesn't exist, create it. - - 7. Remove any existing entries. - - 8. Add an entry for your Debian operating system. - - The possible entries are: - - - On Debian Wheezy - - deb https://apt.dockerproject.org/repo debian-wheezy main - - - On Debian Jessie - - deb https://apt.dockerproject.org/repo debian-jessie main - - - On Debian Stretch/Sid - - deb https://apt.dockerproject.org/repo debian-stretch main - - > **Note**: Docker does not provide packages for all architectures. To install docker on - > a multi-architecture system, add an `[arch=...]` clause to the entry. Refer to the - > [Debian Multiarch wiki](https://wiki.debian.org/Multiarch/HOWTO#Setting_up_apt_sources) - > for details. - - 9. Save and close the file. - - 10. Update the `APT` package index. - - $ sudo apt-get update - - 11. Verify that `APT` is pulling from the right repository. - - $ apt-cache policy docker-engine - - From now on when you run `apt-get upgrade`, `APT` pulls from the new apt repository. +$ sudo apt-get install curl \ + linux-image-extra-$(uname -r) \ + linux-image-extra-virtual +``` ## Install Docker -Before installing Docker, make sure you have set your `APT` repository correctly as described in the prerequisites. +You can install Docker in different ways, depending on your needs: -1. Update the `APT` package index. +- Most users + [set up Docker's repositories](#install-using-the-repository) and install + from them, for ease of installation and upgrade tasks. This is the + recommended approach. - $ sudo apt-get update +- Some users download the DEB package and install it manually and manage + upgrades completely manually. -2. Install Docker. +- Some users cannot use the official Docker repositories, and must rely on + the version of Docker that comes with their operating system. This version of + Docker may be out of date. Those users should consult their operating system + documentation and not follow these procedures. - $ sudo apt-get install docker-engine +### Install using the repository -3. Start the `docker` daemon. +Before you install Docker for the first time on a new host machine, you need to +set up the Docker repository. Afterward, you can install, update, or downgrade +Docker from the repository. - $ sudo service docker start +#### Set up the repository -4. Verify `docker` is installed correctly. +1. Install packages to allow `apt` to use a repository over HTTPS: - $ sudo docker run hello-world + **Jessie or Stretch**: + + ```bash + $ sudo apt-get install apt-transport-https \ + ca-certificates \ + software-properties-common + ``` + + **Wheezy**: + + ```bash + $ sudo apt-get install apt-transport-https \ + ca-certificates \ + python-software-properties + ``` + +2. Add Docker's official GPG key: + + ```bash + $ curl -s http://yum.dockerproject.org/gpg | sudo apt-key add + ``` + + > **Note**: The URL is correct, even for Linux distributions that use `APT`. + + Verify that the key ID is `58118E89F3A912897C070ADBF76221572C52609D`. + + ```bash + $ apt-key fingerprint 58118E89F3A912897C070ADBF76221572C52609D + + pub 4096R/2C52609D 2015-07-14 + Key fingerprint = 5811 8E89 F3A9 1289 7C07 0ADB F762 2157 2C52 609D + uid Docker Release Tool (releasedocker) + ``` + +3. Use the following command to set up the **stable** repository. To also + enable the **testing** repository, add the words `testing` after `main` on + the last line. + **Do not use these unstable repositories on production systems or for non-testing workloads.** + + ```bash + $ sudo add-apt-repository \ + "deb https://apt.dockerproject.org/repo/pool/ \ + $(lsb_release -cs) \ + main" + ``` + + To disable the `testing` repository, you can edit `/etc/apt/sources.list` + and remove the word `testing` from the appropriate line in the file. + +#### Install Docker + +1. Update the `apt` package index. + + ```bash + $ sudo apt-get update + ``` + +2. Install the latest version of Docker, or go to the next step to install a + specific version. Any existing installation of Docker is replaced. + + Use this command to install the latest version of Docker: + + ```bash + $ sudo apt-get -y install docker-engine + ``` + + > **Warning**: If you have both stable and unstable repositories enabled, + > updating to the latest version of Docker by not specifying a version in + > the `apt-get install` or `apt-get update` command will always install the + > highest possible version, which will almost certainly be an unstable one. + +3. On production systems, you should install a specific version of Docker + instead of always using the latest. List the available versions: + + ```bash + $ apt-cache madison docker-engine + docker-engine | 1.13.0-0~stretch | https://apt.dockerproject.org/repo debian-stretch/main amd64 Packages + docker-engine | 1.12.3-0~stretch | https://apt.dockerproject.org/repo debian-stretch/main amd64 Packages + docker-engine | 1.12.2-0~stretch | https://apt.dockerproject.org/repo debian-stretch/main amd64 Packages + docker-engine | 1.12.1-0~stretch | https://apt.dockerproject.org/repo debian-stretch/main amd64 Packages + docker-engine | 1.12.0-0~stretch | https://apt.dockerproject.org/repo debian-stretch/main amd64 Packages + ``` + + The contents of the list depend upon which repositories are enabled, + and will be specific to your version of Debian (indicated by the `stretch` + suffix on the version, in this example). Choose a specific version to + install. The second column is the version string. The third column is the + repository name, which indicates which repository the package is from and + by extension its stability level. To install a specific version, append the + version string to the package name and separate them by an equals sign (`=`): + + ```bash + $ sudo apt-get -y install docker-engine= + ``` + + The Docker daemon starts automatically. + +4. Verify that `docker` is installed correctly by running the `hello-world` + image. + + ```bash + $ sudo docker run hello-world + ``` This command downloads a test image and runs it in a container. When the - container runs, it prints an informational message. Then, it exits. + container runs, it prints an informational message and exits. +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Linux postinstall](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. -## Giving non-root access +#### Upgrade Docker -The `docker` daemon always runs as the `root` user and the `docker` -daemon binds to a Unix socket instead of a TCP port. By default that -Unix socket is owned by the user `root`, and so, by default, you can -access it with `sudo`. +To upgrade Docker, first run `sudo apt-get update`, then follow the +[installation instructions](#install-docker), choosing the new version you want +to install. -If you (or your Docker installer) create a Unix group called `docker` -and add users to it, then the `docker` daemon will make the ownership of -the Unix socket read/writable by the `docker` group when the daemon -starts. The `docker` daemon must always run as the root user, but if you -run the `docker` client as a user in the `docker` group then you don't -need to add `sudo` to all the client commands. From Docker 0.9.0 you can -use the `-G` flag to specify an alternative group. +### Install from a package -> **Warning**: -> The `docker` group (or the group specified with the `-G` flag) is -> `root`-equivalent; see [*Docker Daemon Attack Surface*](../../security/security.md#docker-daemon-attack-surface) details. +If you cannot use Docker's repository to install Docker, you can download the +`.deb` file for your release and install it manually. You will need to download +a new file each time you want to upgrade Docker. -**Example:** +1. Go to [https://apt.dockerproject.org/repo/pool/main/d/docker-engine/](https://apt.dockerproject.org/repo/pool/main/d/docker-engine/) + and download the `.deb` file for the Docker version you want to install and + for your version of Debian. - # Add the docker group if it doesn't already exist. - $ sudo groupadd docker + > **Note**: To install a testing version, change the word `main` in the + > URL to `testing`. Do not use unstable versions of Docker in production + > or for non-testing workloads. - # Add the connected user "${USER}" to the docker group. - # Change the user name to match your preferred user. - # You may have to logout and log back in again for - # this to take effect. - $ sudo gpasswd -a ${USER} docker +2. Install Docker, changing the path below to the path where you downloaded + the Docker package. - # Restart the Docker daemon. - $ sudo service docker restart + ```bash + $ sudo dpkg -i /path/to/package.deb + ``` -## Upgrade Docker + The Docker daemon starts automatically. -To install the latest version of Docker with `apt-get`: +3. Verify that `docker` is installed correctly by running the `hello-world` + image. - $ sudo apt-get upgrade docker-engine + ```bash + $ sudo docker run hello-world + ``` -## Uninstall + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. -To uninstall the Docker package: +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Post-installation steps for Linux](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. +#### Upgrade Docker + +To upgrade Docker, download the newer package file and repeat the +[installation procedure](#install-from-a-package), pointing to the new file. + +## Uninstall Docker + +1. Uninstall the Docker package: + + ```bash $ sudo apt-get purge docker-engine + ``` -To uninstall the Docker package and dependencies that are no longer needed: - - $ sudo apt-get autoremove --purge docker-engine - -The above commands will not remove images, containers, volumes, or user created -configuration files on your host. If you wish to delete all images, containers, -and volumes run the following command: +2. Images, containers, volumes, or customized configuration files on your host + are not automatically removed. To delete all images, containers, and + volumes: + ```bash $ sudo rm -rf /var/lib/docker + ``` -You must delete the user created configuration files manually. +You must delete any edited configuration files manually. -## What next? +## Next steps -Continue with the [User Guide](../../userguide/index.md). +- Continue to [Post-installation steps for Linux](linux-postinstall.md) + +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/fedora.md b/engine/installation/linux/fedora.md index fe25248dcd..9b8768c778 100644 --- a/engine/installation/linux/fedora.md +++ b/engine/installation/linux/fedora.md @@ -1,251 +1,243 @@ --- -description: Instructions for installing Docker on Fedora. -keywords: Docker, Docker documentation, Fedora, requirements, linux +description: Instructions for installing Docker on Fedora +keywords: Docker, Docker documentation, requirements, apt, installation, fedora, rpm, install, uninstall, upgrade, update redirect_from: - /engine/installation/fedora/ -title: Install Docker on Fedora +title: Get Docker for Fedora --- -Docker is supported on Fedora version 23, and 24. These instructions install -Docker using release packages and installation mechanisms managed by Docker, to -be sure that you get the latest version of Docker. If you wish to install using -Fedora-managed packages, consult your Fedora release documentation. +To get started with Docker on Fedora, make sure you +[meet the prerequisites](#prerequisites), then +[install Docker](#install-docker). ## Prerequisites -Docker requires a 64-bit OS and version 3.10 or higher of the Linux kernel. +### OS requirements -To check your current kernel version, open a terminal and use `uname -r` to -display your kernel version: +To install Docker, you need the 64-bit version of one of these Fedora versions: + +- 24 +- 25 + +### Remove unofficial Docker packages + +Fedora's operating system repositories contain an older version of Docker, with +the package name `docker` instead of `docker-engine`. If you installed this version +of Docker, remove it using the following command: ```bash -$ uname -r -3.19.5-100.fc21.x86_64 +$ sudo dnf -y remove docker ``` -If your kernel is at an older version, you must update it. +The contents of `/var/lib/docker` are not removed, so any images, containers, +or volumes you created using the older version of Docker are preserved. -Finally, it is recommended that you fully update your system. Keep in mind -that your system should be fully patched to fix any potential kernel bugs. -Any reported kernel bugs may have already been fixed on the latest kernel -packages. +## Install Docker -## Install Docker Engine +You can install Docker in different ways, depending on your needs: -There are two ways to install Docker Engine. You can [install using the `dnf` -package manager](#install-with-dnf). Or you can use `curl` [with the `get.docker.com` -site](#install-with-the-script). This second method runs an installation script -which also installs via the `dnf` package manager. +- Most users + [set up Docker's repositories](#install-using-the-repository) and install + from them, for ease of installation and upgrade tasks. This is the + recommended approach. -### Install with DNF +- Some users download the RPM package and install it manually and manage + upgrades completely manually. -1. Log into your machine as a user with `sudo` or `root` privileges. +- Some users cannot use third-party repositories, and must rely on the version + of Docker in the Fedora repositories. This version of Docker may be out of + date. Those users should consult the Fedora documentation and not follow these + procedures. -2. Make sure your existing packages are up-to-date. +### Install using the repository + +Before you install Docker for the first time on a new host machine, you need to +set up the Docker repository. Afterward, you can install, update, or downgrade +Docker from the repository. + +#### Set up the repository + +1. Install the `dnf-plugins.core` package which provides the commands to manage + your DNF repositories from the command line. ```bash - $ sudo dnf update + $ sudo dnf -y install dnf-plugins-core ``` -3. Add the `yum` repo. +2. Use the following command to set up the **stable** repository: ```bash - $ sudo tee /etc/yum.repos.d/docker.repo <<-'EOF' - [dockerrepo] - name=Docker Repository - baseurl=https://yum.dockerproject.org/repo/main/fedora/$releasever/ - enabled=1 - gpgcheck=1 - gpgkey=https://yum.dockerproject.org/gpg - EOF + $ sudo dnf config-manager \ + --add-repo \ + https://docs.docker.com/engine/installation/linux/repo_files/fedora/docker.repo ``` -4. Install the Docker package. +3. **Optional**: Enable the **testing** repository. This repository is included + in the `docker.repo` file above but is disabled by default. You can enable + it alongside the stable repository. Do not use unstable repositories on + on production systems or for non-testing workloads. + + > **Warning**: If you have both stable and unstable repositories enabled, + > updating without specifying a version in the `dnf install` or `dnf update` + > command will always install the highest possible version, which will + > almost certainly be an unstable one. ```bash - $ sudo dnf install docker-engine + $ sudo dnf config-manager --set-enabled docker-testing ``` -5. Enable the service. + You can disable the `testing` repository by running the `dnf config-manager` + command with the `--set-disabled` flag. To re-enable it, use the + `--set-enabled` flag The following command disables the `testing` + repository. ```bash - $ sudo systemctl enable docker.service + $ sudo dnf config-manager --set-disabled docker-testing ``` -6. Start the Docker daemon. +#### Install Docker + +1. Update the `dnf` package index. ```bash - $ sudo systemctl start docker + $ sudo dnf -y check-update ``` - -7. Verify `docker` is installed correctly by running a test image in a container. - - $ sudo docker run --rm hello-world - - Unable to find image 'hello-world:latest' locally - latest: Pulling from library/hello-world - c04b14da8d14: Pull complete - Digest: sha256:0256e8a36e2070f7bf2d0b0763dbabdd67798512411de4cdcf9431a1feb60fd9 - Status: Downloaded newer image for hello-world:latest - - Hello from Docker! - This message shows that your installation appears to be working correctly. - - To generate this message, Docker took the following steps: - 1. The Docker client contacted the Docker daemon. - 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. - 3. The Docker daemon created a new container from that image which runs the - executable that produces the output you are currently reading. - 4. The Docker daemon streamed that output to the Docker client, which sent it - to your terminal. - - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash - - Share images, automate workflows, and more with a free Docker Hub account: - https://hub.docker.com - - For more examples and ideas, visit: - https://docs.docker.com/engine/userguide/ - -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read our Systemd article to -learn how to [customize your Systemd Docker daemon options](../../admin/systemd.md). - -### Install with the script - -You use the same installation procedure for all versions of Fedora. - -1. Log into your machine as a user with `sudo` or `root` privileges. - -2. Make sure your existing packages are up-to-date. +2. Install the latest version of Docker, or go to the next step to install a + specific version. ```bash - $ sudo dnf update + $ sudo dnf -y install docker-engine ``` -3. Run the Docker installation script. + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating without specifying a version in the `dnf install` + > or `dnf update` command will always install the highest possible version, + > which will almost certainly be an unstable one. + +3. On production systems, you should install a specific version of Docker + instead of always using the latest. List the available versions. + This example uses the `sort -r` command to sort the results by version + number, highest to lowest. + + > **Note**: This `dnf list` command only shows binary packages. To show + > source packages as well, omit the `.x86_64` from the package name. ```bash - $ curl -fsSL https://get.docker.com/ | sh + $ dnf list docker-engine.x86_64 --showduplicates |sort -r + + docker-engine.x86_64 1.13.0-1.fc24 docker-main + docker-engine.x86_64 1.13.0-0.5.rc5.fc24 docker-testing + docker-engine.x86_64 1.13.0-0.4.rc4.fc24 docker-testing + docker-engine.x86_64 1.13.0-0.3.rc3.fc24 docker-testing + docker-engine.x86_64 1.13.0-0.2.rc2.fc24 docker-testing + docker-engine.x86_64 1.13.0-0.1.rc1.fc24 docker-testing + docker-engine.x86_64 1.12.5-1.fc24 docker-main + docker-engine.x86_64 1.12.4-1.fc24 docker-main + docker-engine.x86_64 1.12.3-1.fc24 docker-main + docker-engine.x86_64 1.12.2-1.fc24 docker-main + docker-engine.x86_64 1.12.1-1.fc24 docker-main + docker-engine.x86_64 1.12.0-1.fc24 docker-main ``` - This script adds the `docker.repo` repository and installs Docker. - -4. Enable the service. + The contents of the list depend upon which repositories are enabled, and + will be specific to your version of Fedora (indicated by the `.fc24` suffix + on the version, in this example). Choose a specific version to install. The + second column is the version string. The third column is the repository + name, which indicates which repository the package is from and by extension + its stability level. To install a specific version, append the version + string to the package name and separate them by a hyphen (`-`): ```bash - $ sudo systemctl enable docker.service + $ sudo dnf -y install docker-engine- ``` -5. Start the Docker daemon. + The Docker daemon starts automatically. - ```bash - $ sudo systemctl start docker - ``` - -6. Verify `docker` is installed correctly by running a test image in a container. +4. Verify that `docker` is installed correctly by running the `hello-world` + image. ```bash $ sudo docker run hello-world ``` -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read our Systemd article to -learn how to [customize your Systemd Docker daemon options](../../admin/systemd.md). + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. -## Create a docker group +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Linux postinstall](linux-postinstall.md) to allow non-privileged +users to run Docker commands and for other optional configuration steps. -The `docker` daemon binds to a Unix socket instead of a TCP port. By default -that Unix socket is owned by the user `root` and other users can access it with -`sudo`. For this reason, `docker` daemon always runs as the `root` user. +#### Upgrade Docker -To avoid having to use `sudo` when you use the `docker` command, create a Unix -group called `docker` and add users to it. When the `docker` daemon starts, it -makes the ownership of the Unix socket read/writable by the `docker` group. +To upgrade Docker, first run `sudo dnf check-update`, then follow the +[installation instructions](#install-docker), choosing the new version you want +to install. ->**Warning**: The `docker` group is equivalent to the `root` user; For details ->on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../../security/security.md#docker-daemon-attack-surface) for details. +### Install from a package -To create the `docker` group and add your user: +If you cannot use Docker's repository to install Docker, you can download the +`.rpm` file for your release and install it manually. You will need to download +a new file each time you want to upgrade Docker. -1. Log into your machine as a user with `sudo` or `root` privileges. +1. Go to [https://yum.dockerproject.org/repo/main/fedora/](https://yum.dockerproject.org/repo/main/fedora/) + and choose the subdirectory for your Fedora version. Download the `.rpm` + file for the Docker version you want to install. -2. Create the `docker` group. + > **Note**: To install a testing version, change the word `main` in the + > URL to `testing`. Do not use unstable versions of Docker in production + > or for non-testing workloads. + +2. Install Docker, changing the path below to the path where you downloaded + the Docker package. ```bash - $ sudo groupadd docker + $ sudo dnf -y install /path/to/package.rpm ``` -3. Add your user to `docker` group. + The Docker daemon starts automatically. + +3. Verify that `docker` is installed correctly by running the `hello-world` + image. ```bash - $ sudo usermod -aG docker your_username` + $ sudo docker run hello-world ``` -4. Log out and log back in. + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. - This ensures your user is running with the correct permissions. +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Post-installation steps for Linux](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. -5. Verify that your user is in the docker group by running `docker` without `sudo`. +#### Upgrade Docker + +To upgrade Docker, download the newer package file and repeat the +[installation procedure](#install-from-a-package), using `dnf -y upgrade` +instead of `dnf -y install`, and pointing to the new file. + + +## Uninstall Docker + +1. Uninstall the Docker package: ```bash - $ docker run hello-world + $ sudo dnf -y remove docker-engine ``` -## Start the docker daemon at boot - -Configure the Docker daemon to start automatically when the host starts: - -```bash -$ sudo systemctl enable docker -``` - -## Running Docker with a manually-defined network - -If you manually configure your network using `systemd-network` with `systemd` version 219 or higher, containers you start with Docker may be unable to access your network. -Beginning with version 220, the forwarding setting for a given network (`net.ipv4.conf..forwarding`) defaults to *off*. This setting prevents IP forwarding. It also conflicts with Docker which enables the `net.ipv4.conf.all.forwarding` setting within a container. - -To work around this, edit the `.network` file in -`/usr/lib/systemd/network/` on your Docker host (ex: `/usr/lib/systemd/network/80-container-host0.network`) add the following block: - -``` -[Network] -... -IPForward=kernel -# OR -IPForward=true -... -``` - -This configuration allows IP forwarding from the container as expected. - -## Uninstall - -You can uninstall the Docker software with `dnf`. - -1. List the installed Docker packages. +2. Images, containers, volumes, or customized configuration files on your host + are not automatically removed. To delete all images, containers, and + volumes: ```bash - $ dnf list installed | grep docker - - docker-engine.x86_64 1.7.1-0.1.fc21 @/docker-engine-1.7.1-0.1.fc21.el7.x86_64 + $ sudo rm -rf /var/lib/docker ``` -2. Remove the package. +You must delete any edited configuration files manually. - ```bash - $ sudo dnf -y remove docker-engine.x86_64 - ``` +## Next steps - This command does not remove images, containers, volumes, or user-created - configuration files on your host. +- Continue to [Post-installation steps for Linux](linux-postinstall.md) -3. To delete all images, containers, and volumes, run the following command: - - ```bash - $ rm -rf /var/lib/docker - ``` - -4. Locate and delete any user-created configuration files. +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/linux-postinstall.md b/engine/installation/linux/linux-postinstall.md new file mode 100644 index 0000000000..c9806dfb88 --- /dev/null +++ b/engine/installation/linux/linux-postinstall.md @@ -0,0 +1,405 @@ +--- +description: Optional post-installation steps for Linux +keywords: Docker, Docker documentation, requirements, apt, installation, ubuntu, install, uninstall, upgrade, update +title: Post-installation steps for Linux +--- + + +This section contains optional procedures for configuring Linux hosts to work +better with Docker. + +* [Manage Docker as a non-root user](#manage-docker-as-a-non-root-user) +* [Configure Docker to start on boot](#configure-docker-to-start-on-boot) +* [Allow access to the remote API through a firewall](#allow-access-to-the-remote-api-through-a-firewall) +* [Troubleshooting](#troubleshooting) + +## Manage Docker as a non-root user + +The `docker` daemon binds to a Unix socket instead of a TCP port. By default +that Unix socket is owned by the user `root` and other users can only access it +using `sudo`. The `docker` daemon always runs as the `root` user. + +If you don't want to use `sudo` when you use the `docker` command, create a Unix +group called `docker` and add users to it. When the `docker` daemon starts, it +makes the ownership of the Unix socket read/writable by the `docker` group. + +> **Warning**: The `docker` group grants privileges equivalent to the `root` +> user. For details on how this impacts security in your system, see +> [*Docker Daemon Attack Surface*](../../security/security.md#docker-daemon-attack-surface). + +To create the `docker` group and add your user: + +1. Create the `docker` group. + ```bash + $ sudo groupadd docker + ``` + +2. Add your user to the `docker` group. + + ```bash + $ sudo usermod -aG docker $USER + ``` + +3. Log out and log back in so that your group membership is re-evaluated. + +4. Verify that you can `docker` commands without `sudo`. + + ```bash + $ docker run hello-world + ``` + + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +## Configure Docker to start on boot + +Most current Linux distributions (RHEL, CentOS, Fedora, Ubuntu 16.04 and higher) +use [`systemd`](#systemd) to manage which services start when the system boots. +Ubuntu 14.10 and below use [`upstart`](#upstart). Oracle Linux 6 uses +`chkconfig`. + +### `systemd` + +```bash +$ sudo systemctl enable docker +``` + +To disable this behavior, use `disable` instead. + +```bash +$ sudo systemctl disable docker +``` + +If you need to add an HTTP Proxy, set a different directory or partition for the +Docker runtime files, or make other customizations, see +[customize your systemd Docker daemon options](../../admin/systemd.md). + +### `upstart` + +Docker is automatically configured to start on boot using +`upstart`. To disable this behavior, use the following command: + +```bash +$ echo manual | sudo tee /etc/init/docker.override +``` + +### `chkconfig` + +```bash +$ sudo chkconfig docker on +``` + +## Use a different storage engine + +For information about the different storage engines, see +[Storage drivers](../userguide/storagedriver/index.md). The default storage +engine and the list of supported storage engines depend on your host's +Linux distribution and available kernel drivers. + +## Troubleshooting + +### `Cannot connect to the Docker daemon` + +If you see an error such as the following, your Docker client may be configured +to connect to a Docker daemon on a different host, and that host may not be +reachable. + +```none +Cannot connect to the Docker daemon. Is 'docker daemon' running on this host? +``` + +To see which host your client is configured to connect to, check the value of +the `DOCKER_HOST` variable in your environment. + + +```bash +$ env | grep DOCKER_HOST +``` + +If this command returns a value, the Docker client is set to connect to a +Docker daemon running on that host. If it is unset, the Docker client is set to +connect to the Docker daemon running on the local host. If it is set in error, +use the following command to unset it: + + +```bash +$ unset DOCKER_HOST +``` + +You may need to edit your environment in files such as `~/.bashrc` or +`~/.profile` to prevent the `DOCKER_HOST` variable from being set +erroneously. + +If `DOCKER_HOST` is set as intended, verify that the Docker daemon is running +on the remote host and that a firewall or network outage is not preventing you +from connecting. + +### IP forwarding problems + +If you manually configure your network using `systemd-network` with `systemd` +version 219 or higher, Docker containers may be unable to access your network. +Beginning with `systemd` version 220, the forwarding setting for a given network +(`net.ipv4.conf..forwarding`) defaults to *off*. This setting +prevents IP forwarding. It also conflicts with Docker's behavior of enabling +the `net.ipv4.conf.all.forwarding` setting within containers. + +To work around this on RHEL, CentOS, or Fedora, edit the `.network` +file in `/usr/lib/systemd/network/` on your Docker host +(ex: `/usr/lib/systemd/network/80-container-host0.network`) and add the +following block within the `[Network]` section. + +``` +[Network] +... +IPForward=kernel +# OR +IPForward=true +... +``` + +This configuration allows IP forwarding from the container as expected. + + +### `DNS resolver found in resolv.conf and containers can't use it` + +Linux systems which use a GUI often have a network manager running, which uses a +`dnsmasq` instance running on a loopback address such as `127.0.0.1` or +`127.0.1.1` to cache DNS requests, and adds this entry to +`/etc/resolv.conf`. The `dnsmasq` service speeds up +DNS look-ups and also provides DHCP services. This configuration will not work +within a Docker container which has its own network namespace, because +the Docker container resolves loopback addresses such as `127.0.0.1` to +**itself**, and it is very unlikely to be running a DNS server on its own +loopback address. + +If Docker detects that no DNS server referenced in `/etc/resolv.conf` is a fully +functional DNS server, the following warning occurs and Docker uses the public +DNS servers provided by Google at `8.8.8.8` and `8.8.4.4` for DNS resolution. + +```none +WARNING: Local (127.0.0.1) DNS resolver found in resolv.conf and containers +can't use it. Using default external servers : [8.8.8.8 8.8.4.4] +``` + +If you see this warning, first check to see if you use `dnsmasq`: + +```bash +$ ps aux |grep dnsmasq +``` + +If your container needs to resolve hosts which are internal to your network, the +public nameservers will not be adequate. You have two choices: + +- You can specify a DNS server for Docker to use, **or** +- You can disable `dnsmasq` in NetworkManager. If you do this, NetworkManager + will add your true DNS nameserver to `/etc/resolv.conf`, but you will lose the + possible benefits of `dnsmasq`. + +**You only need to use one of these methods.** + +### Specify DNS servers for Docker + +The default location of the configuration file is `/etc/docker/daemon.json`. You +can change the location of the configuration file using the `--config-file` +daemon flag. The documentation below assumes the configuration file is located +at `/etc/docker/daemon.json`. + +1. . Create or edit the Docker daemon configuration file, which defaults to + `/etc/docker/daemon.json` file, which controls the Docker daemon + configuration. + + ```bash + sudo nano /etc/docker/daemon.json + ``` + +2. Add a `dns` key with one or more IP addresses as values. If the file has + existing contents, you only need to add or edit the `dns` line. + ```json + { + "dns": ["8.8.8.8", "8.8.4.4"] + } + ``` + + If your internal DNS server cannot resolve public IP addresses, include at + least one DNS server which can, so that you can connect to Docker Hub and so + that your containers can resolve internet domain names. + + Save and close the file. + +3. Restart the Docker daemon. + + ```bash + $ sudo service docker restart + ``` + +4. Verify that Docker can resolve external IP addresses by trying to pull an + image: + + ```bash + $ docker pull hello-world + ``` + +5. If necessary, verify that Docker containers can resolve an internal hostname + by pinging it. + + ```bash + $ docker run --rm -it alpine ping -c4 + + PING google.com (192.168.1.2): 56 data bytes + 64 bytes from 192.168.1.2: seq=0 ttl=41 time=7.597 ms + 64 bytes from 192.168.1.2: seq=1 ttl=41 time=7.635 ms + 64 bytes from 192.168.1.2: seq=2 ttl=41 time=7.660 ms + 64 bytes from 192.168.1.2: seq=3 ttl=41 time=7.677 ms + ``` + +#### Disable `dnsmasq` + +##### Ubuntu + +If you prefer not to change the Docker daemon's configuration to use a specific +IP address, follow these instructions to disable `dnsmasq` in NetworkManager. + +1. Edit the `/etc/NetworkManager/NetworkManager.conf` file. + +2. Comment out the `dns=dnsmasq` line by adding a `#` character to the beginning + of the line. + + ```none + # dns=dnsmasq + ``` + + Save and close the file. + +4. Restart both NetworkManager and Docker. As an alternative, you can reboot + your system. + + ```bash + $ sudo restart network-manager + $ sudo restart docker + ``` + +##### RHEL, CentOS, or Fedora + +To disable `dnsmasq` on RHEL, CentOS, or Fedora: + +1. Disable the `dnsmasq` service: + + ```bash + $ sudo service dnsmasq stop + + $ sudo systemctl disable dnsmasq + ``` + +2. Configure the DNS servers manually using the + [Red Hat documentation](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/s1-networkscripts-interfaces.html){ :target="_blank" class="_"}. + +### Allow access to the remote API through a firewall + +If you run a firewall on the same host as you run Docker and you want to access +the Docker Remote API from another host and remote access is enabled, you need +to configure your firewall to allow incoming connections on the Docker port, +which defaults to `2376` if TLS encrypted transport is enabled or `2375` +otherwise. + +#### Specific instructions for UFW + +[UFW (Uncomplicated Firewall)](https://help.ubuntu.com/community/UFW) drops all +forwarding traffic and all incoming traffic by default. If you want to access +the Docker Remote API from another host and you have enabled remote access, you +need to configure UFW to allow incoming connections on the Docker port, which +defaults to `2376` if TLS encrypted transport is enabled or `2375` otherwise. By +default, Docker runs **without** TLS enabled. If you do not use TLS, you are +strongly discouraged from allowing access to the Docker Remote API from remote +hosts, to prevent remote privilege-escalation attacks. + +To configure UFW and allow incoming connections on the Docker port: + +1. Verify that UFW is enabled. + + ```bash + $ sudo ufw status + ``` + + If `ufw` is not enabled, the remaining steps will not be helpful. + +2. Edit the UFW configuration file, which is usually `/etc/default/ufw` or +`/etc/sysconfig/ufw`. Set the `DEFAULT_FORWARD_POLICY` policy to `ACCEPT`. + + ```none + DEFAULT_FORWARD_POLICY="ACCEPT" + ``` + + Save and close the file. + +3. If you need to enable access to the Docker Remote API from external hosts + and understand the security implications (see the section before this + procedure), then configure UFW to allow incoming connections on the Docker port, + which is 2375 if you do not use TLS, and 2376 if you do. + + ```bash + $ sudo ufw allow 2376/tcp + ``` + +4. Reload UFW. + ```bash + $ sudo ufw reload + ``` + +### `Your kernel does not support cgroup swap limit capabilities` + +You may see messages similar to the following when working with an image: + +```none +WARNING: Your kernel does not support swap limit capabilities. Limitation discarded. +``` + +If you don't need these capabilities, you can ignore the warning. You can +enable these capabilities in your kernel by following these instructions. Memory +and swap accounting incur an overhead of about 1% of the total available +memory and a 10% overall performance degradation, even if Docker is not running. + +1. Log into Ubuntu as a user with `sudo` privileges. + +2. Edit the `/etc/default/grub` file. + +3. Add or edit the `GRUB_CMDLINE_LINUX` line to add the following two key-value + pairs: + + ```none + GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1" + ``` + + Save and close the file. + +4. Update GRUB. + + ```bash + $ sudo update-grub + ``` + + If your GRUB configuration file has incorrect syntax, an error will occur. + In this case, steps 3 and 4. + +6. Reboot your system. Memory and swap accounting are enabled and the warning + does not occur. + + +### Troubleshooting Oracle Linux + +#### Docker unmounts `btrfs` filesystem on shutdown + +If you're running Docker using the `btrfs` storage engine and you stop the Docker +service, it unmounts the `btrfs` filesystem during the shutdown process. Ensure +that the filesystem is mounted properly before restarting the Docker service. + +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`. + +#### SElinux support on Oracle Linux 7 + +SElinux must be set to `Permissive` or `Disabled` in `/etc/sysconfig/selinux` to +use the `btrfs` storage engine on Oracle Linux 7. + +## Next steps + +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/oracle.md b/engine/installation/linux/oracle.md index 7b6f365667..3be2f15c2d 100644 --- a/engine/installation/linux/oracle.md +++ b/engine/installation/linux/oracle.md @@ -1,204 +1,236 @@ --- -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 redirect_from: - /engine/installation/oracle/ -title: Install Docker on Oracle Linux +title: Get Docker for Oracle Linux --- -Docker is supported on Oracle Linux 6 and 7. You do not require an Oracle Linux -Support subscription to install Docker on Oracle Linux. +To get started with Docker on Oracle Linux, make sure you +[meet the prerequisites](#prerequisites), then +[install Docker](#install-docker). ## Prerequisites -Due to current Docker limitations, Docker is only able to run only on the x86_64 -architecture. Docker requires the use of the Unbreakable Enterprise Kernel -Release 4 (4.1.12) or higher on Oracle Linux. This kernel supports the Docker -btrfs storage engine on both Oracle Linux 6 and 7. +### OS requirements -## Install +To install Docker, you need the 64-bit version of Oracle Linux 6 or 7, running +the Unbreakable Enterprise Kernel Release 4 (4.1.12) or higher. This kernel +supports the Docker `btrfs` storage engine. +### Remove unofficial Docker packages -> **Note**: The procedure below installs binaries built by Docker. These binaries -> are not covered by Oracle Linux support. To ensure Oracle Linux support, please -> follow the installation instructions provided in the -> [Oracle Linux documentation](https://docs.oracle.com/en/operating-systems/?tab=2). -> -> The installation instructions for Oracle Linux 6 and 7 can be found in [Chapter 2 of -> the Docker User's Guide](https://docs.oracle.com/cd/E52668_01/E75728/html/docker_install_upgrade.html) +Oracle's repositories contain an older version of Docker, with the package name +`docker` instead of `docker-engine`. If you installed this version of Docker, +remove it using the following command: - -1. Log into your machine as a user with `sudo` or `root` privileges. - -2. Make sure your existing yum packages are up-to-date. - - $ sudo yum update - -3. Add the yum repo yourself. - - For version 6: - - $ sudo tee /etc/yum.repos.d/docker.repo <<-EOF - [dockerrepo] - name=Docker Repository - baseurl=https://yum.dockerproject.org/repo/main/oraclelinux/6 - enabled=1 - gpgcheck=1 - gpgkey=https://yum.dockerproject.org/gpg - EOF - - For version 7: - - $ cat >/etc/yum.repos.d/docker.repo <<-EOF - [dockerrepo] - name=Docker Repository - baseurl=https://yum.dockerproject.org/repo/main/oraclelinux/7 - enabled=1 - gpgcheck=1 - gpgkey=https://yum.dockerproject.org/gpg - EOF - -4. Install the Docker package. - - $ sudo yum install docker-engine - -5. Start the Docker daemon. - - On Oracle Linux 6: - - $ sudo service docker start - - On Oracle Linux 7: - - $ sudo systemctl start docker.service - -6. Verify `docker` is installed correctly by running a test image in a container. - - $ sudo docker run hello-world - -## Optional configurations - -This section contains optional procedures for configuring your Oracle Linux to work -better with Docker. - -* [Create a docker group](#create-a-docker-group) -* [Configure Docker to start on boot](#configure-docker-to-start-on-boot) -* [Use the btrfs storage engine](#use-the-btrfs-storage-engine) - -### Create a Docker group - -The `docker` daemon binds to a Unix socket instead of a TCP port. By default -that Unix socket is owned by the user `root` and other users can access it with -`sudo`. For this reason, `docker` daemon always runs as the `root` user. - -To avoid having to use `sudo` when you use the `docker` command, create a Unix -group called `docker` and add users to it. When the `docker` daemon starts, it -makes the ownership of the Unix socket read/writable by the `docker` group. - ->**Warning**: The `docker` group is equivalent to the `root` user; For details ->on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../../security/security.md#docker-daemon-attack-surface) for details. - -To create the `docker` group and add your user: - -1. Log into Oracle Linux as a user with `sudo` privileges. - -2. Create the `docker` group. - - $ sudo groupadd docker - -3. Add your user to `docker` group. - - $ sudo usermod -aG docker username - -4. Log out and log back in. - - This ensures your user is running with the correct permissions. - -5. Verify your work by running `docker` without `sudo`. - - $ docker run hello-world - - If this fails with a message similar to this: - - Cannot connect to the Docker daemon. Is 'docker daemon' running on this host? - - Check that the `DOCKER_HOST` environment variable is not set for your shell. - If it is, unset it. - -### Configure Docker to start on boot - -You can configure the Docker daemon to start automatically at boot. - -On Oracle Linux 6: - -``` -$ sudo chkconfig docker on +```bash +$ sudo yum -y remove docker ``` -On Oracle Linux 7: +The contents of `/var/lib/docker` are not removed, so any images, containers, +or volumes you created using the older version of Docker are preserved. -``` -$ sudo systemctl enable docker.service -``` +## Install Docker -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read our systemd article to -learn how to [customize your systemd Docker daemon options](../../admin/systemd.md). +You can install Docker in different ways, depending on your needs: -### Use the btrfs storage engine +- 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. -Docker on Oracle Linux 6 and 7 supports the use of the btrfs storage engine. -Before enabling btrfs support, ensure that `/var/lib/docker` is stored on a -btrfs-based filesystem. Review [Chapter -5](http://docs.oracle.com/cd/E37670_01/E37355/html/ol_btrfs.html) of the [Oracle -Linux Administrator's Solution -Guide](http://docs.oracle.com/cd/E37670_01/E37355/html/index.html) for details -on how to create and mount btrfs filesystems. +- Some users download the RPM package and install it manually and manage + upgrades completely manually. -To enable btrfs support on Oracle Linux: +- 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 + follow these procedures. -1. Ensure that `/var/lib/docker` is on a btrfs filesystem. +### Install using the repository -2. Edit `/etc/sysconfig/docker` and add `-s btrfs` to the `OTHER_ARGS` field. +Before you install Docker for the first time on a new host machine, you need to +set up the Docker repository. Afterward, you can install, update, or downgrade +Docker from the repository. -3. Restart the Docker daemon: +#### Set up the repository -## Uninstallation +1. Use the following command to set up the **stable** repository: -To uninstall the Docker package: + ```bash + $ sudo yum-config-manager \ + --add-repo \ + https://docs.docker.com/engine/installation/linux/repo_files/oracle/docker.repo + ``` - $ sudo yum -y remove docker-engine +2. **Optional**: Enable the **testing** repository. This repository is included + in the `docker.repo` file above but is disabled by default. You can enable + it alongside the stable repository. Do not use unstable repositories on + on production systems or for non-testing workloads. -The above command will not remove images, containers, volumes, or user created -configuration files on your host. If you wish to delete all images, containers, -and volumes run the following command: + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating without specifying a version in the `yum install` + > or `yum update` command will always install the highest possible version, + > which will almost certainly be an unstable one. - $ rm -rf /var/lib/docker + ```bash + $ sudo yum-config-manager --set-enabled docker-testing + ``` -You must delete the user created configuration files manually. + You can disable the `testing` repository by running the `yum-config-manager` + command with the `--set-disabled` flag. To re-enable it, use the + `--set-enabled` flag. The following command disables the `testing` + repository. -## Known issues + ```bash + $ sudo yum-config-manager --set-disabled docker-testing + ``` -### Docker unmounts btrfs filesystem on shutdown -If you're running Docker using the btrfs storage engine and you stop the Docker -service, it will unmount the btrfs filesystem during the shutdown process. You -should ensure the filesystem is mounted properly prior to restarting the Docker -service. +#### Install Docker -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. +1. Update the `yum` package index. -### SElinux support on Oracle Linux 7 -SElinux must be set to `Permissive` or `Disabled` in `/etc/sysconfig/selinux` to -use the btrfs storage engine on Oracle Linux 7. + ```bash + $ sudo yum -y check-update + ``` +2. Install the latest version of Docker, or go to the next step to install a + specific version. -## Further issues? + ```bash + $ sudo yum -y install docker-engine + ``` -If you have a current Basic or Premier Support Subscription for Oracle Linux, -you can report any issues you have with the installation of Docker via a Service -Request at [My Oracle Support](https://support.oracle.com). + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating Docker without specifying a version in the + > `yum install` or `yum upgrade` command will always install the highest + > available version, which will almost certainly be an unstable one. -If you do not have an Oracle Linux Support Subscription, you can use the [Oracle -Linux -Forum](https://community.oracle.com/community/server_%26_storage_systems/linux/oracle_linux) for community-based support. +3. On production systems, you should install a specific version of Docker + instead of always using the latest. List the available versions. + This example uses the `sort -r` command to sort the results by version + number, highest to lowest. + + > **Note**: This `yum list` command only shows binary packages. To show + > source packages as well, omit the `.x86_64` from the package name. + + ```bash + $ yum list docker-engine.x86_64 --showduplicates |sort -r + + docker-engine.x86_64 1.13.0-1.el7 docker-main + docker-engine.x86_64 1.13.0-0.5.rc5.el7 docker-testing + docker-engine.x86_64 1.13.0-0.4.rc4.el7 docker-testing + docker-engine.x86_64 1.13.0-0.3.rc3.el7 docker-testing + docker-engine.x86_64 1.13.0-0.2.rc2.el7 docker-testing + docker-engine.x86_64 1.13.0-0.1.rc1.el7 docker-testing + docker-engine.x86_64 1.12.5-1.el7 docker-main + docker-engine.x86_64 1.12.4-1.el7 docker-main + docker-engine.x86_64 1.12.3-1.el7 docker-main + docker-engine.x86_64 1.12.2-1.el7 docker-main + docker-engine.x86_64 1.12.1-1.el7 docker-main + docker-engine.x86_64 1.12.0-1.el7 docker-main + ``` + + The contents of the list depend upon which repositories you have enabled, + and will be specific to your version of Oracle Linux (indicated by the + `.el7` suffix on the version, in this example). Choose a specific version to + install. The second column is the version string. The third column is the + repository name, which indicates which repository the package is from and by + extension extension its stability level. To install a specific version, + append the version string to the package name and separate them by a hyphen + (`-`): + + ```bash + $ sudo yum -y install docker-engine- + ``` + + The Docker daemon starts automatically. + +4. Verify that `docker` is installed correctly by running the `hello-world` + image. + + ```bash + $ sudo docker run hello-world + ``` + + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Linux postinstall](linux-postinstall.md) to allow non-privileged +users to run Docker commands and for other optional configuration steps. + +#### Upgrade Docker + +To upgrade Docker, first run `sudo yum check-update`, then follow the +[installation instructions](#install-docker), choosing the new version you want +to install. + +### Install from a package + +If you cannot use Docker's repository to install Docker, you can download the +`.rpm` file for your release and install it manually. You will need to download +a new file each time you want to upgrade Docker. + +1. Go to [https://yum.dockerproject.org/repo/main/oraclelinux/](https://yum.dockerproject.org/repo/main/oraclelinux/) + and choose the subdirectory for your Oracle Linux version. Download the + `.rpm` file for the Docker version you want to install. + + > **Note**: To install a testing version, change the word `main` in the + > URL to `testing`. Do not use unstable versions of Docker in production + > or for non-testing workloads. + +2. Install Docker, changing the path below to the path where you downloaded + the Docker package. + + ```bash + $ sudo yum install /path/to/package.rpm + ``` + + The Docker daemon starts automatically. + +3. Verify that `docker` is installed correctly by running the `hello-world` + image. + + ```bash + $ sudo docker run hello-world + ``` + + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Post-installation steps for Linux](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. + +#### Upgrade Docker + +To upgrade Docker, 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. + + +## Uninstall Docker + +1. Uninstall the Docker package: + + ```bash + $ sudo yum remove docker-engine + ``` + +2. Images, containers, volumes, or customized configuration files on your host + are not automatically removed. To delete all images, containers, and + volumes: + + ```bash + $ sudo rm -rf /var/lib/docker + ``` + +You must delete any edited configuration files manually. + +## Next steps + +- Continue to [Post-installation steps for Linux](linux-postinstall.md) + +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/other.md b/engine/installation/linux/other.md new file mode 100644 index 0000000000..cafba5da66 --- /dev/null +++ b/engine/installation/linux/other.md @@ -0,0 +1,18 @@ +--- +title: Installation on other Linux distributions +description: "Installing Docker on other Linux distributions" +--- + +This section lists installation instructions for community-maintained Docker +distributions. These instructions are not regularly tested. Consider +[installing from binaries](../binaries.md) instead. + +- [Installation on Arch Linux](/engine/installation/linux/archlinux.md) +- [Installation on CRUX Linux](/engine/installation/linux/cruxlinux.md) +- [Installation on Gentoo Linux](/engine/installation/linux/gentoolinux.md) +- [Installation on Raspbian Linux](/engine/installation/linux/raspbian.md) + +## Next steps + +- Continue to [Post-installation steps for Linux](linux-postinstall.md) +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/raspbian.md b/engine/installation/linux/raspbian.md index 242128d388..16efab7fd1 100644 --- a/engine/installation/linux/raspbian.md +++ b/engine/installation/linux/raspbian.md @@ -148,6 +148,6 @@ and volumes run the following command: You must delete the user created configuration files manually. -## What next? +## Next steps Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/repo_files/centos/docker.repo b/engine/installation/linux/repo_files/centos/docker.repo new file mode 100644 index 0000000000..abea668f22 --- /dev/null +++ b/engine/installation/linux/repo_files/centos/docker.repo @@ -0,0 +1,27 @@ +[docker-main] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/main/centos/$releasever/ +enabled=1 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-testing] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/testing/centos/$releasever/ +enabled=1 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-beta] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/beta/centos/$releasever/ +enabled=0 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-nightly] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/nightly/centos/$releasever/ +enabled=0 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg diff --git a/engine/installation/linux/repo_files/fedora/docker.repo b/engine/installation/linux/repo_files/fedora/docker.repo new file mode 100644 index 0000000000..77644ded98 --- /dev/null +++ b/engine/installation/linux/repo_files/fedora/docker.repo @@ -0,0 +1,27 @@ +[docker-main] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/main/fedora/$releasever/ +enabled=1 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-testing] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/testing/fedora/$releasever/ +enabled=1 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-beta] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/beta/fedora/$releasever/ +enabled=0 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-nightly] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/nightly/fedora/$releasever/ +enabled=0 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg diff --git a/engine/installation/linux/repo_files/oracle/docker.repo b/engine/installation/linux/repo_files/oracle/docker.repo new file mode 100644 index 0000000000..b75b213b71 --- /dev/null +++ b/engine/installation/linux/repo_files/oracle/docker.repo @@ -0,0 +1,27 @@ +[docker-main] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/main/oraclelinux/$releasever/ +enabled=1 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-testing] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/testing/oraclelinux/$releasever/ +enabled=1 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-beta] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/beta/oraclelinux/$releasever/ +enabled=0 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg + +[docker-nightly] +name=Docker Repository +baseurl=https://yum.dockerproject.org/repo/nightly/oraclelinux/$releasever/ +enabled=0 +gpgcheck=1 +gpgkey=https://yum.dockerproject.org/gpg diff --git a/engine/installation/linux/rhel.md b/engine/installation/linux/rhel.md index 151e62b7e7..c83bfd9130 100644 --- a/engine/installation/linux/rhel.md +++ b/engine/installation/linux/rhel.md @@ -1,229 +1,237 @@ --- -description: Instructions for installing Docker on Red Hat Enterprise Linux. -keywords: Docker, Docker documentation, requirements, linux, rhel +description: Instructions for installing Docker on RHEL +keywords: Docker, Docker documentation, requirements, installation, rhel, rpm, install, uninstall, upgrade, update redirect_from: - /engine/installation/rhel/ - /installation/rhel/ -title: Install Docker on Red Hat Enterprise Linux +title: Get Docker for Red Hat Enterprise Linux --- -Docker is supported on Red Hat Enterprise Linux 7. These instructions install -Docker using release packages and installation mechanisms managed by Docker, -to be sure that you get the latest version of Docker. If you wish to install -using Red Hat-managed packages, consult your Red Hat release documentation. +To get started with Docker on Red Hat Enterprise Linux (RHEL), make sure you +[meet the prerequisites](#prerequisites), then +[install Docker](#install-docker). ## Prerequisites -Docker requires a 64-bit OS and version 3.10 or higher of the Linux kernel. +### OS requirements -To check your current kernel version, open a terminal and use `uname -r` to -display your kernel version: +To install Docker, you need the 64-bit version of RHEL 7. + +### Remove unofficial Docker packages + +Red Hat's operating system repositories contain an older version of Docker, with +the package name `docker` instead of `docker-engine`. If you installed this +version of Docker, remove it using the following command: ```bash -$ uname -r -3.10.0-229.el7.x86_64 +$ sudo yum -y remove docker ``` -Finally, it is recommended that you fully update your system. Keep in mind -that your system should be fully patched to fix any potential kernel bugs. -Any reported kernel bugs may have already been fixed on the latest kernel -packages. +The contents of `/var/lib/docker` are not removed, so any images, containers, +or volumes you created using the older version of Docker are preserved. -## Install Docker Engine +## Install Docker -There are two ways to install Docker Engine. You can [install using the `yum` -package manager](#install-with-yum). Or you can use `curl` with the [`get.docker.com` -site](#install-with-the-script). This second method runs an installation script -which also installs via the `yum` package manager. +You can install Docker in different ways, depending on your needs: -### Install with yum +- Most users + [set up Docker's repositories](#install-using-the-repository) and install + from them, for ease of installation and upgrade tasks. This is the + recommended approach. -1. Log into your machine as a user with `sudo` or `root` privileges. +- Some users download the RPM package and install it manually and manage + upgrades completely manually. -2. Make sure your existing packages are up-to-date. +- 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 + follow these procedures. + +### Install using the repository + +Before you install Docker for the first time on a new host machine, you need to +set up the Docker repository. Afterward, you can install, update, or downgrade +Docker from the repository. + +#### Set up the repository + +1. Use the following command to set up the **stable** repository: ```bash - $ sudo yum update + $ sudo yum-config-manager \ + --add-repo \ + https://docs.docker.com/engine/installation/linux/repo_files/centos/docker.repo ``` -3. Add the `yum` repo. + > **Note**: The link above is correct for RHEL as well as CentOS. + +2. **Optional**: Enable the **testing** repository. This repository is included + in the `docker.repo` file above but is disabled by default. You can enable + it alongside the stable repository. Do not use unstable repositories on + on production systems or for non-testing workloads. + + > **Warning**: If you have both stable and unstable repositories enabled, + > updating without specifying a version in the `yum install` or `yum update` + > command will always install the highest possible version, which will + > almost certainly be an unstable one. ```bash - $ sudo tee /etc/yum.repos.d/docker.repo <<-'EOF' - [dockerrepo] - name=Docker Repository - baseurl=https://yum.dockerproject.org/repo/main/centos/7/ - enabled=1 - gpgcheck=1 - gpgkey=https://yum.dockerproject.org/gpg - EOF + $ sudo yum-config-manager --set-enabled docker-testing ``` -4. Install the Docker package. + You can disable the `testing` repository by running the `yum-config-manager` + command with the `--set-disabled` flag. To re-enable it, use the + `--set-enabled` flag. The following command disables the `testing` + repository. ```bash - $ sudo yum install docker-engine + $ sudo yum-config-manager --set-disabled docker-testing ``` -5. Enable the service. +#### Install Docker + +1. Update the `yum` package index. ```bash - $ sudo systemctl enable docker.service + $ sudo yum -y check-update ``` - -6. Start the Docker daemon. +2. Install the latest version of Docker, or go to the next step to install a + specific version. ```bash - $ sudo systemctl start docker + $ sudo yum -y install docker-engine ``` -7. Verify `docker` is installed correctly by running a test image in a container. + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating without specifying a version in the `yum install` + > or `yum update` command will always install the highest possible version, + > which will almost certainly be an unstable one. - $ sudo docker run --rm hello-world +3. On production systems, you should install a specific version of Docker + instead of always using the latest. List the available versions. + This example uses the `sort -r` command to sort the results by version + number, highest to lowest. - Unable to find image 'hello-world:latest' locally - latest: Pulling from library/hello-world - c04b14da8d14: Pull complete - Digest: sha256:0256e8a36e2070f7bf2d0b0763dbabdd67798512411de4cdcf9431a1feb60fd9 - Status: Downloaded newer image for hello-world:latest - - Hello from Docker! - This message shows that your installation appears to be working correctly. - - To generate this message, Docker took the following steps: - 1. The Docker client contacted the Docker daemon. - 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. - 3. The Docker daemon created a new container from that image which runs the - executable that produces the output you are currently reading. - 4. The Docker daemon streamed that output to the Docker client, which sent it - to your terminal. - - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash - - Share images, automate workflows, and more with a free Docker Hub account: - https://hub.docker.com - - For more examples and ideas, visit: - https://docs.docker.com/engine/userguide/ - -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read our Systemd article to -learn how to [customize your Systemd Docker daemon options](../../admin/systemd.md). - -### Install with the script - -1. Log into your machine as a user with `sudo` or `root` privileges. - -2. Make sure your existing packages are up-to-date. + > **Note**: This `yum list` command only shows binary packages. To show + > source packages as well, omit the `.x86_64` from the package name. ```bash - $ sudo yum update + $ yum list docker-engine.x86_64 --showduplicates |sort -r + + docker-engine.x86_64 1.13.0-1.el7 docker-main + docker-engine.x86_64 1.13.0-0.5.rc5.el7 docker-testing + docker-engine.x86_64 1.13.0-0.4.rc4.el7 docker-testing + docker-engine.x86_64 1.13.0-0.3.rc3.el7 docker-testing + docker-engine.x86_64 1.13.0-0.2.rc2.el7 docker-testing + docker-engine.x86_64 1.13.0-0.1.rc1.el7 docker-testing + docker-engine.x86_64 1.12.5-1.el7 docker-main + docker-engine.x86_64 1.12.4-1.el7 docker-main + docker-engine.x86_64 1.12.3-1.el7 docker-main + docker-engine.x86_64 1.12.2-1.el7 docker-main + docker-engine.x86_64 1.12.1-1.el7 docker-main + docker-engine.x86_64 1.12.0-1.el7 docker-main ``` -3. Run the Docker installation script. + The contents of the list depend upon which repositories you have enabled, + and will be specific to your version of RHEL (indicated by the `.el7` suffix + on the version, in this example). Choose a specific version to install. The + second column is the version string. The third column is the repository + name, which indicates which repository the package is from and by extension + extension its stability level. To install a specific version, append the + version string to the package name and separate them by a hyphen (`-`): ```bash - $ curl -fsSL https://get.docker.com/ | sh + $ sudo yum -y install docker-engine- ``` - This script adds the `docker.repo` repository and installs Docker. + The Docker daemon starts automatically. -4. Enable the service. - - ```bash - $ sudo systemctl enable docker.service - ``` - -5. Start the Docker daemon. - - ```bash - $ sudo systemctl start docker - ``` - -6. Verify `docker` is installed correctly by running a test image in a container. +4. Verify that `docker` is installed correctly by running the `hello-world` + image. ```bash $ sudo docker run hello-world ``` -If you need to add an HTTP Proxy, set a different directory or partition for the -Docker runtime files, or make other customizations, read our Systemd article to -learn how to [customize your Systemd Docker daemon options](../../admin/systemd.md). + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. -## Create a docker group +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Linux postinstall](linux-postinstall.md) to allow non-privileged +users to run Docker commands and for other optional configuration steps. -The `docker` daemon binds to a Unix socket instead of a TCP port. By default -that Unix socket is owned by the user `root` and other users can access it with -`sudo`. For this reason, `docker` daemon always runs as the `root` user. +#### Upgrade Docker -To avoid having to use `sudo` when you use the `docker` command, create a Unix -group called `docker` and add users to it. When the `docker` daemon starts, it -makes the ownership of the Unix socket read/writable by the `docker` group. +To upgrade Docker, first run `sudo yum check-update`, then follow the +[installation instructions](#install-docker), choosing the new version you want +to install. ->**Warning**: The `docker` group is equivalent to the `root` user; For details ->on how this impacts security in your system, see [*Docker Daemon Attack ->Surface*](../../security/security.md#docker-daemon-attack-surface) for details. +### Install from a package -To create the `docker` group and add your user: +If you cannot use the official Docker repository to install Docker, you can +download the `.rpm` file for your release and install it manually. You will +need to download a new file each time you want to upgrade Docker. -1. Log into your machine as a user with `sudo` or `root` privileges. +1. Go to [https://yum.dockerproject.org/repo/main/centos/](https://yum.dockerproject.org/repo/main/centos/) + and choose the subdirectory for your RHEL version. The above URL is correct + for RHEL as well as CentOS. Download the `.rpm` file for the Docker version + you want to install. -2. Create the `docker` group. + > **Note**: To install a testing version, change the word `main` in the + > URL to `testing`. Do not use unstable versions of Docker in production + > or for non-testing workloads. + +2. Install Docker, changing the path below to the path where you downloaded + the Docker package. ```bash - $ sudo groupadd docker + $ sudo yum install /path/to/package.rpm ``` -3. Add your user to `docker` group. + The Docker daemon starts automatically. + +3. Verify that `docker` is installed correctly by running the `hello-world` + image. ```bash - $ sudo usermod -aG docker your_username` + $ sudo docker run hello-world ``` -4. Log out and log back in. + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. - This ensures your user is running with the correct permissions. +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Post-installation steps for Linux](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. -5. Verify that your user is in the docker group by running `docker` without `sudo`. +#### Upgrade Docker + +To upgrade Docker, 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. + + +## Uninstall Docker + +1. Uninstall the Docker package: ```bash - $ docker run hello-world + $ sudo yum -y remove docker-engine ``` -## Start the docker daemon at boot - -Configure the Docker daemon to start automatically when the host starts: - -```bash -$ sudo systemctl enable docker -``` - -## Uninstall - -You can uninstall the Docker software with `yum`. - -1. List the installed Docker packages. +2. Images, containers, volumes, or customized configuration files on your host + are not automatically removed. To delete all images, containers, and + volumes: ```bash - $ yum list installed | grep docker - - docker-engine.x86_64 1.7.1-0.1.el7@/docker-engine-1.7.1-0.1.el7.x86_64 + $ sudo rm -rf /var/lib/docker ``` -2. Remove the package. +You must delete any edited configuration files manually. - ```bash - $ sudo yum -y remove docker-engine.x86_64 - ``` +## Next steps - This command does not remove images, containers, volumes, or user-created - configuration files on your host. +- Continue to [Post-installation steps for Linux](linux-postinstall.md) -3. To delete all images, containers, and volumes, run the following command: - - ```bash - $ rm -rf /var/lib/docker - ``` - -4. Locate and delete any user-created configuration files. +- Continue with the [User Guide](../../userguide/index.md). diff --git a/engine/installation/linux/ubuntu.md b/engine/installation/linux/ubuntu.md new file mode 100644 index 0000000000..7b4ef7c302 --- /dev/null +++ b/engine/installation/linux/ubuntu.md @@ -0,0 +1,239 @@ +--- +description: Instructions for installing Docker on Ubuntu +keywords: Docker, Docker documentation, requirements, apt, installation, ubuntu, install, uninstall, upgrade, update +redirect_from: +- /engine/installation/ubuntulinux/ +- /installation/ubuntulinux/ +- /engine/installation/linux/ubuntulinux/ +title: Get Docker for Ubuntu +--- + +To get started with Docker on Ubuntu, make sure you +[meet the prerequisites](#prerequisites), then +[install Docker](#install-docker). + +## Prerequisites + +### OS requirements + +To install Docker, you need the 64-bit version of one of these Ubuntu versions: + +- Yakkety 16.10 +- Xenial 16.04 (LTS) +- Trusty 14.04 (LTS) + +### Recommended extra packages + +You need `curl` if you don't have it. Unless you have a strong reason not to, +install the `linux-image-extra-*` packages, which allow Docker to use the `aufs` +storage drivers. **This applies to all versions of Ubuntu**. + +```bash +$ sudo apt-get update + +$ sudo apt-get install curl \ + linux-image-extra-$(uname -r) \ + linux-image-extra-virtual +``` + +## Install Docker + +You can install Docker in different ways, depending on your needs: + +- Most users + [set up Docker's repositories](#install-using-the-repository) and install + 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 + upgrades completely manually. + +- Some users cannot use the official Docker repositories, and must rely on + the version of Docker that comes with their operating system. This version of + Docker may be out of date. Those users should consult their operating system + documentation and not follow these procedures. + +### Install using the repository + +Before you install Docker for the first time on a new host machine, you need to +set up the Docker repository. Afterward, you can install, update, or downgrade +Docker from the repository. + +#### Set up the repository + +1. Install packages to allow `apt` to use a repository over HTTPS: + + ```bash + $ sudo apt-get install apt-transport-https \ + ca-certificates + ``` + +2. Add Docker's official GPG key: + + ```bash + $ curl -s http://yum.dockerproject.org/gpg | sudo apt-key add + ``` + + > **Note**: The URL is correct, even for Linux distributions that use `APT`. + + Verify that the key ID is `58118E89F3A912897C070ADBF76221572C52609D`. + + ```bash + $ apt-key fingerprint 58118E89F3A912897C070ADBF76221572C52609D + + pub 4096R/2C52609D 2015-07-14 + Key fingerprint = 5811 8E89 F3A9 1289 7C07 0ADB F762 2157 2C52 609D + uid Docker Release Tool (releasedocker) + ``` + +3. Use the following command to set up the **stable** repository. To also + enable the **testing** repository, add the words `testing` after `main` on + the last line. + **Do not use these unstable repositories on production systems or for non-testing workloads.** + + ```bash + $ sudo add-apt-repository \ + "deb https://apt.dockerproject.org/repo/pool/ \ + $(lsb_release -cs) \ + main" + ``` + + To disable the `testing` repository, you can edit `/etc/apt/sources.list` + and remove the word `testing` from the appropriate line in the file. + +#### Install Docker + +1. Update the `apt` package index. + + ```bash + $ sudo apt-get update + ``` + +2. Install the latest version of Docker, or go to the next step to install a + specific version. Any existing installation of Docker is replaced. + + Use this command to install the latest version of Docker: + + ```bash + $ sudo apt-get -y install docker-engine + ``` + + > **Warning**: If you have both stable and unstable repositories enabled, + > installing or updating without specifying a version in the + > `apt-get install` or `apt-get update` command will always install the + > highest possible version, which will almost certainly be an unstable one. + +3. On production systems, you should install a specific version of Docker + instead of always using the latest. List the available versions. + + ```bash + $ apt-cache madison docker-engine + + docker-engine | 1.13.0-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages + docker-engine | 1.12.3-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages + docker-engine | 1.12.2-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages + docker-engine | 1.12.1-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages + docker-engine | 1.12.0-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages + ``` + + The contents of the list depend upon which repositories are enabled, + and will be specific to your version of Ubuntu (indicated by the `xenial` + suffix on the version, in this example). Choose a specific version to + install. The second column is the version string. The third column is the + repository name, which indicates which repository the package is from and + by extension its stability level. To install a specific version, append the + version string to the package name and separate them by an equals sign (`=`): + + ```bash + $ sudo apt-get -y install docker-engine= + ``` + + The Docker daemon starts automatically. + +4. Verify that `docker` is installed correctly by running the `hello-world` + image. + + ```bash + $ sudo docker run hello-world + ``` + + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Linux postinstall](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. + +#### Upgrade Docker + +To upgrade Docker, first run `sudo apt-get update`, then follow the +[installation instructions](#install-docker), choosing the new version you want +to install. + +### Install from a package + +If you cannot use Docker's repository to install Docker, you can download the +`.deb` file for your release and install it manually. You will need to download +a new file each time you want to upgrade Docker. + +1. Go to [https://apt.dockerproject.org/repo/pool/main/d/docker-engine/](https://apt.dockerproject.org/repo/pool/main/d/docker-engine/) + and download the `.deb` file for the Docker version you want to install and + for your version of Ubuntu. + + > **Note**: To install a testing version, change the word `main` in the + > URL to `testing`. Do not use unstable versions of Docker in production + > or for non-testing workloads. + +2. Install Docker, changing the path below to the path where you downloaded + the Docker package. + + ```bash + $ sudo dpkg -i /path/to/package.deb + ``` + + The Docker daemon starts automatically. + +3. Verify that `docker` is installed correctly by running the `hello-world` + image. + + ```bash + $ sudo docker run hello-world + ``` + + This command downloads a test image and runs it in a container. When the + container runs, it prints an informational message and exits. + +Docker is installed and running. You need to use `sudo` to run Docker commands. +Continue to [Post-installation steps for Linux](linux-postinstall.md) to allow +non-privileged users to run Docker commands and for other optional configuration +steps. + +#### Upgrade Docker + +To upgrade Docker, download the newer package file and repeat the +[installation procedure](#install-from-a-package), pointing to the new file. + +## Uninstall Docker + +1. Uninstall the Docker package: + + ```bash + $ sudo apt-get purge docker-engine + ``` + +2. Images, containers, volumes, or customized configuration files on your host + are not automatically removed. To delete all images, containers, and + volumes: + + ```bash + $ sudo rm -rf /var/lib/docker + ``` + +You must delete any edited configuration files manually. + +## Next steps + +- Continue to [Post-installation steps for Linux](linux-postinstall.md) + +- Continue with the [User Guide](../../userguide/index.md).