docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Linux installation improvements (#1560)

This commit is contained in:
Misty Stanley-Jones 2017-02-10 11:31:50 -08:00 committed by GitHub
parent 81d21e9352
commit afef955a13
12 changed files with 109 additions and 865 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_data/toc.yaml
View File

@ -52,7 +52,7 @@ toc:
- path: /engine/installation/linux/fedora/
title: Fedora
- path: /engine/installation/linux/debian/
title: Debian
title: Debian or Raspbian
- path: /engine/installation/linux/oracle/
title: Oracle Linux
- path: /engine/installation/linux/suse/

23
engine/installation/binaries.md
View File

@ -8,8 +8,10 @@ title: Install Docker from binaries
> a dynamically-linked Docker package for your Linux distribution.
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.**
a supported platform, you can try installing from static binaries. If possible,
you should use packages built for your operating system, and use your operating
system's package management system to manage Docker installation and upgrades.
Be aware that 32-bit static binary archives do not include the Docker daemon.
Static binaries for the Docker daemon binary are only available for Linux (as
`dockerd`) and Windows Server 2016 or Windows 10 (as `dockerd.exe`). Static
@ -38,7 +40,11 @@ meets the prerequisites:
[#3485](https://github.com/docker/docker/issues/3485),
[#4568](https://github.com/docker/docker/issues/4568)).
#### Enable AppArmor and SELinux when possible
#### Secure your environment as much as possible
##### OS considerations
Enable SELinux or AppArmor if possible.
It is recommended to use AppArmor or SELinux if your Linux distribution supports
either of the two. This helps improve security and blocks certain
@ -50,6 +56,14 @@ instructions for enabling and configuring AppArmor or SELinux.
> work-around to make Docker or its containers run. Instead, configure it
> correctly to fix any problems.
##### Docker daemon considerations
- Enable `seccomp` security profiles if possible. See
[Enabling `seccomp` for Docker](/engine/security/seccomp.md).
- Enable user namespaces if possible. See the
[Daemon user namespace options](/engine/reference/commandline/dockerd/#/daemon-user-namespace-options).
### Install static binaries
1. Download the static binary archive. You can download either the latest
@ -85,7 +99,6 @@ instructions for enabling and configuring AppArmor or SELinux.
If you need to start the daemon with additional options, modify the above
command accordingly.
>>>>>>> c02c644... Rewrite and reorganize Linux install instructions
5. Verify that Docker is installed correctly by running the `hello-world`
image.
@ -143,7 +156,7 @@ The macOS binary includes the Docker client only. It does not include the
container runs, it prints an informational message and exits.
## Install server and binaries on Windows
## Install server and client binaries on Windows
You can install Docker from binaries on Windows Server 2016 or Windows 10.

6
engine/installation/linux/centos.md
View File

@ -23,7 +23,7 @@ the package name `docker` instead of `docker-engine`. If you installed this
version of Docker, remove it using the following command:
```bash
$ sudo yum -y remove docker
$ sudo yum -y remove docker docker-common container-selinux
```
You may also have to remove the package `docker-selinux` which conflicts with
@ -77,8 +77,8 @@ Docker from the repository.
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.
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,
> installing or updating without specifying a version in the `yum install`

90
engine/installation/linux/debian.md
View File

@ -1,9 +1,10 @@
---
description: Instructions for installing Docker on Debian
keywords: Docker, Docker documentation, requirements, apt, installation, debian, install, uninstall, upgrade, update
keywords: Docker, Docker documentation, requirements, apt, installation, debian, raspbian, install, uninstall, upgrade, update
redirect_from:
- /engine/installation/debian/
title: Get Docker for Debian
- /engine/installation/linux/raspbian/
title: Get Docker for Debian or Raspbian
---
To get started with Docker on Debian, make sure you
@ -14,10 +15,11 @@ To get started with Docker on Debian, make sure you
### OS requirements
To install Docker, you need the 64-bit version of one of these Debian versions:
To install Docker, you need the 64-bit version of one of these Debian or
Raspbian versions:
- Stretch (testing)
- Jessie 8.0 (LTS)
- Jessie 8.0 (LTS) / Raspbian Jessie
- Wheezy 7.7 (LTS)
#### Extra steps for Wheezy 7.7
@ -34,16 +36,6 @@ To install Docker, you need the 64-bit version of one of these Debian versions:
- Enable the `backports` repository. See the
[Debian documentation](https://backports.debian.org/Instructions/){: target="_blank" class"_"}.
### Recommended extra packages
You need `curl` if you don't have it.
```bash
$ sudo apt-get update
$ sudo apt-get install curl
```
## Install Docker
You can install Docker in different ways, depending on your needs:
@ -74,27 +66,29 @@ Docker from the repository.
**Jessie or Stretch**:
```bash
$ sudo apt-get install apt-transport-https \
ca-certificates \
software-properties-common
$ sudo apt-get install -y --no-install-recommends
apt-transport-https \
ca-certificates \
curl \
software-properties-common
```
**Wheezy**:
```bash
$ sudo apt-get install apt-transport-https \
ca-certificates \
python-software-properties
$ sudo apt-get install -y --no-install-recommends \
apt-transport-https \
ca-certificates \
curl \
python-software-properties
```
2. Add Docker's official GPG key:
```bash
$ curl -fsSL https://yum.dockerproject.org/gpg | sudo apt-key add -
$ curl -fsSL https://apt.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
@ -105,20 +99,32 @@ Docker from the repository.
uid Docker Release Tool (releasedocker) <docker@docker.com>
```
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.**
3. Use the following command to set up the **stable** repository.
```bash
$ sudo add-apt-repository \
"deb https://apt.dockerproject.org/repo/ \
debian-$(lsb_release -cs) \
main"
```
> **Note**: The `lsb_release -cs` sub-command below returns the name of your
> Debian distribution, such as `jessie`.
To disable the `testing` repository, you can edit `/etc/apt/sources.list`
and remove the word `testing` from the appropriate line in the file.
- **Debian**:
```bash
$ sudo add-apt-repository \
"deb https://apt.dockerproject.org/repo/ \
debian-$(lsb_release -cs) \
main"
```
- **Raspbian**:
```bash
$ sudo add-apt-repository \
"deb https://apt.dockerproject.org/repo/ \
raspbian-$(lsb_release -cs) \
main"
```
To enable the `testing` repository, you can edit `/etc/apt/sources.list`
and add the word `testing` after `main` on the appropriate line of the file.
**Do not use unstable repositories on production systems or for non-testing workloads.**
#### Install Docker
@ -166,7 +172,11 @@ Docker from the repository.
$ sudo apt-get -y install docker-engine=<VERSION_STRING>
```
The Docker daemon starts automatically.
On Debian, the Docker daemon starts automatically. On Raspbian, start Docker:
```bash
$ sudo service docker start
```
4. Verify that `docker` is installed correctly by running the `hello-world`
image.
@ -197,7 +207,7 @@ 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 Debian.
for your version of Debian or Raspbian.
> **Note**: To install a testing version, change the word `main` in the
> URL to `testing`. Do not use unstable versions of Docker in production
@ -210,7 +220,11 @@ a new file each time you want to upgrade Docker.
$ sudo dpkg -i /path/to/package.deb
```
The Docker daemon starts automatically.
On Debian, the Docker daemon starts automatically. On Raspbian, start Docker:
```bash
$ sudo service docker start
```
3. Verify that `docker` is installed correctly by running the `hello-world`
image.

6
engine/installation/linux/fedora.md
View File

@ -26,7 +26,7 @@ the package name `docker` instead of `docker-engine`. If you installed this vers
of Docker, remove it using the following command:
```bash
$ sudo dnf -y remove docker
$ sudo dnf -y remove docker docker-common container-selinux
```
You may also have to remove the package `docker-selinux` which conflicts with the
@ -81,8 +81,8 @@ Docker from the repository.
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.
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`

4
engine/installation/linux/oracle.md
View File

@ -94,8 +94,8 @@ Docker from the repository.
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.
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,
> installing or updating without specifying a version in the `yum install`

1
engine/installation/linux/other.md
View File

@ -10,7 +10,6 @@ distributions. These instructions are not regularly tested. Consider
- [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

153
engine/installation/linux/raspbian.md
View File

@ -1,153 +0,0 @@
---
redirect_from:
- /engine/installation/raspbian/
description: Instructions for installing Docker on Raspbian.
keywords: Docker, Docker documentation, installation, raspbian
title: Install on Raspbian
---
Docker is supported on the following versions of Raspbian:
- *Raspbian Jessie*
>**Note**: If you previously installed Docker using `APT`, make sure you update
your `APT` sources to the new `APT` repository.
## Prerequisites
Docker requires your kernel to be 3.10 at minimum. The latest 3.10 minor
version or a newer maintained version are also acceptable.
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 check your current kernel version, open a terminal and use `uname -r` to
display your kernel version:
$ uname -r
### Update your apt repository
Docker's `APT` repository contains Docker 1.12.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. Update package information, ensure that APT works with the `https` method, and that CA certificates are installed.
$ apt-get update
$ apt-get install apt-transport-https ca-certificates
4. Add the new `GPG` key.
$ apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
5. Open the `/etc/apt/sources.list.d/docker.list` file in your favorite editor.
If the file doesn't exist, create it.
6. Remove any existing entries.
7. Add an entry for your Raspbian operating system.
deb https://apt.dockerproject.org/repo raspbian-jessie main
8. Save and close the file.
9. Update the `APT` package index.
$ apt-get update
10. 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.
## Install Docker
Before installing Docker, make sure you have set your `APT` repository correctly as described in the prerequisites.
1. Update the `APT` package index.
$ sudo apt-get update
2. Install Docker.
$ sudo apt-get install docker-engine
3. Start the `docker` daemon.
$ sudo service docker start
4. Verify `docker` is installed correctly.
$ sudo docker run armhf/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.
## Giving non-root access
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`.
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.
> **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.
**Example:**
# Add the docker group if it doesn't already exist.
$ sudo groupadd docker
# 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
# Restart the Docker daemon.
$ sudo service docker restart
## Upgrade Docker
To install the latest version of Docker with `apt-get`:
$ apt-get upgrade docker-engine
## Uninstall
To uninstall the Docker package:
$ 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:
$ rm -rf /var/lib/docker
You must delete the user created configuration files manually.
## Next steps
Continue with the [User Guide](../../userguide/index.md).

6
engine/installation/linux/rhel.md
View File

@ -24,7 +24,7 @@ the package name `docker` instead of `docker-engine`. If you installed this
version of Docker, remove it using the following command:
```bash
$ sudo yum -y remove docker
$ sudo yum -y remove docker docker-common container-selinux
```
You may also have to remove the package `docker-selinux` which conflicts with
@ -80,8 +80,8 @@ Docker from the repository.
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.
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`

4
engine/installation/linux/suse.md
View File

@ -68,8 +68,8 @@ Docker from the repository.
```
2. **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.
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 `zypper install` or

41
engine/installation/linux/ubuntu.md
View File

@ -22,16 +22,16 @@ To install Docker, you need the 64-bit version of one of these Ubuntu versions:
- Xenial 16.04 (LTS)
- Trusty 14.04 (LTS)
### Recommended extra packages
### Recommended extra packages for Trusty 14.04
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**.
Unless you have a strong reason not to, install the
`linux-image-extra-*` packages, which allow Docker to use the `aufs` storage
drivers.
```bash
$ sudo apt-get update
$ sudo apt-get install curl \
$ sudo apt-get install -y --no-install-recommends \
linux-image-extra-$(uname -r) \
linux-image-extra-virtual
```
@ -64,19 +64,20 @@ Docker from the repository.
1. Install packages to allow `apt` to use a repository over HTTPS:
```bash
$ sudo apt-get install apt-transport-https \
software-properties-common \
ca-certificates
```
$ sudo apt-get -y --no-install-recommends install \
curl \
apt-transport-https \
ca-certificates \
curl \
software-properties-common
```
2. Add Docker's official GPG key:
```bash
$ curl -fsSL https://yum.dockerproject.org/gpg | sudo apt-key add -
$ curl -fsSL https://apt.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
@ -87,27 +88,27 @@ Docker from the repository.
uid Docker Release Tool (releasedocker) <docker@docker.com>
```
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.**
3. Use the following command to set up the **stable** repository.
> **Note**: The `lsb_release -cs` sub-command below returns the name of your
> Debian distribution, such as `xenial`.
```bash
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository \
"deb https://apt.dockerproject.org/repo/ \
ubuntu-$(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.
To enable the `testing` repository, you can edit `/etc/apt/sources.list`
and add the word `testing` after `main` on the appropriate line of the file.
**Do not use unstable repositories on production systems or for non-testing workloads.**
> **Note**: Sometimes, in a distribution like Linux Mint, you might have
> to change `ubuntu-$(lsb_release -cs)` to your parent Ubuntu distribution.
> example: If you are using `Linux Mint Rafaela`, you could type in `ubuntu-trusty`
#### Install Docker
1. Update the `apt` package index.

630
engine/installation/linux/ubuntulinux.md
View File

@ -1,630 +0,0 @@
---
description: Instructions for installing Docker on Ubuntu
keywords: Docker, Docker documentation, requirements, apt, installation, ubuntu
redirect_from:
- /engine/installation/ubuntulinux/
- /installation/ubuntulinux/
title: Install Docker on Ubuntu
---
Docker is supported on these Ubuntu operating systems:
- Ubuntu Yakkety 16.10
- Ubuntu Xenial 16.04 (LTS)
- Ubuntu Trusty 14.04 (LTS)
- Ubuntu Precise 12.04 (LTS)
This page instructs you to install Docker on Ubuntu, using packages provided by
Docker. Using these packages ensures you get the latest official
release of Docker. If you are required to install using Ubuntu-managed packages,
consult the Ubuntu documentation. Some files and commands may be different if
you use Ubuntu-managed packages.
>**Note**: Ubuntu Utopic 14.10, 15.10, and 15.04 exist in Docker's `APT`
repository but are no longer officially supported.
## Prerequisites
Docker has two important installation requirements:
- Docker only works on a 64-bit Linux installation.
- Docker requires version 3.10 or higher of the Linux kernel. Kernels older than
3.10 lack some of the features required to run Docker containers and contain
known bugs which cause data loss and frequently panic under certain conditions.
To check your current kernel version, open a terminal and use `uname -r` to
display your kernel version:
```bash
$ uname -r
3.11.0-15-generic
```
### Update your apt sources
To set `APT` to use packages from the Docker repository:
1. Log into your machine as a user with `sudo` or `root` privileges.
2. Open a terminal window.
3. Update package information, ensure that APT works with the `https` method,
and that CA certificates are installed.
```bash
$ sudo apt-get update
$ sudo apt-get install apt-transport-https ca-certificates
```
4. Add the new `GPG` key. This commands downloads the key with the ID
`58118E89F3A912897C070ADBF76221572C52609D` from the keyserver
`hkp://ha.pool.sks-keyservers.net:80` and adds it to the `adv` keychain.
For more info, see the output of `man apt-key`.
```bash
$ sudo apt-key adv \
--keyserver hkp://ha.pool.sks-keyservers.net:80 \
--recv-keys 58118E89F3A912897C070ADBF76221572C52609D
```
If the above keyserver is not available, try `hkp://pgp.mit.edu:80` or
`hkp://keyserver.ubuntu.com:80`.
5. Find the entry in the table below which corresponds to your Ubuntu version.
This determines where APT will search for Docker packages. When possible,
run a long-term support (LTS) edition of Ubuntu.
| Ubuntu version | Repository |
| ------------------- | ------------------------------------------------------------ |
| Precise 12.04 (LTS) | `deb https://apt.dockerproject.org/repo ubuntu-precise main` |
| Trusty 14.04 (LTS) | `deb https://apt.dockerproject.org/repo ubuntu-trusty main` |
| Xenial 16.04 (LTS) | `deb https://apt.dockerproject.org/repo ubuntu-xenial main` |
| Yakkety 16.10 | `deb https://apt.dockerproject.org/repo ubuntu-yakkety main` |
>**Note**: Docker does not provide packages for all architectures. Binary artifacts
are built nightly, and you can download them from
https://master.dockerproject.org. To install docker on a multi-architecture
system, add an `[arch=...]` clause to the entry. Refer to
[Debian Multiarch wiki](https://wiki.debian.org/Multiarch/HOWTO#Setting_up_apt_sources)
for details.
6. Run the following command, substituting the entry for your operating system
for the placeholder `<REPO>`.
```bash
$ echo "<REPO>" | sudo tee /etc/apt/sources.list.d/docker.list
```
7. Update the `APT` package index.
```bash
$ sudo apt-get update
```
8. Verify that `APT` is pulling from the right repository.
When you run the following command, an entry is returned for each version of
Docker that is available for you to install. Each entry should have the URL
`https://apt.dockerproject.org/repo/`. The version currently installed is
marked with `***`.The output below is truncated.
```bash
$ apt-cache policy docker-engine
docker-engine:
Installed: 1.12.2-0~trusty
Candidate: 1.12.2-0~trusty
Version table:
*** 1.12.2-0~trusty 0
500 https://apt.dockerproject.org/repo/ ubuntu-trusty/main amd64 Packages
100 /var/lib/dpkg/status
1.12.1-0~trusty 0
500 https://apt.dockerproject.org/repo/ ubuntu-trusty/main amd64 Packages
1.12.0-0~trusty 0
500 https://apt.dockerproject.org/repo/ ubuntu-trusty/main amd64 Packages
```
From now on when you run `apt-get upgrade`, `APT` pulls from the new repository.
### Prerequisites by Ubuntu Version
- Ubuntu Yakkety 16.10
- Ubuntu Xenial 16.04 (LTS)
- Ubuntu Trusty 14.04 (LTS)
For Ubuntu Trusty, Yakkety, and Xenial, it's recommended to install the
`linux-image-extra-*` kernel packages. The `linux-image-extra-*` packages
allows you use the `aufs` storage driver.
To install the `linux-image-extra-*` packages:
1. Open a terminal on your Ubuntu host.
2. Update your package manager.
```bash
$ sudo apt-get update
```
3. Install the recommended packages.
```bash
$ sudo apt-get install linux-image-extra-$(uname -r) linux-image-extra-virtual
```
4. Go ahead and [install Docker](ubuntulinux.md#install-the-latest-version).
#### Ubuntu Precise 12.04 (LTS)
For Ubuntu Precise, Docker requires the 3.13 kernel version. If your kernel
version is older than 3.13, you must upgrade it. Refer to this table to see
which packages are required for your environment:
| Package | Description |
| --------------------------------- | ----------- |
| `linux-image-generic-lts-trusty` | Generic Linux kernel image. This kernel has AUFS built in. This is required to run Docker. |
| `linux-headers-generic-lts-trusty`| Allows packages such as ZFS and VirtualBox guest additions which depend on them. If you didn't install the headers for your existing kernel, then you can skip these headers for the"trusty" kernel. If you're unsure, you should include this package for safety. |
| `xserver-xorg-lts-trusty` | Optional in non-graphical environments without Unity/Xorg. **Required** when running Docker on machine with a graphical environment. |
| `ligbl1-mesa-glx-lts-trusty` | To learn more about the reasons for these packages, read the installation instructions for backported kernels, specifically the [LTS Enablement Stack](https://wiki.ubuntu.com/Kernel/LTSEnablementStack). Refer to note 5 under each version. |
To upgrade your kernel and install the additional packages, do the following:
1. Open a terminal on your Ubuntu host.
2. Update your package manager.
```bash
$ sudo apt-get update
```
3. Install both the required and optional packages.
```bash
$ sudo apt-get install linux-image-generic-lts-trusty
```
Repeat this step for other packages you need to install.
4. Reboot your host to use the updated kernel.
```bash
$ sudo reboot
```
5. After your system reboots, go ahead and
[install Docker](ubuntulinux.md#install-the-latest-version).
## Install the latest version
Make sure you have satisfied all the
[prerequisites](ubuntulinux.md#prerequisites), then follow these steps.
>**Note**: For production systems, it is recommended that you
[install a specific version](ubuntulinux.md#install-a-specific-version) so that
you do not accidentally update Docker. You should plan upgrades for production
systems carefully.
1. Log into your Ubuntu installation as a user with `sudo` privileges.
2. Update your `APT` package index.
```bash
$ sudo apt-get update
```
3. Install Docker.
```bash
$ sudo apt-get install docker-engine
```
4. Start the `docker` daemon.
```bash
$ sudo service docker start
```
5. 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.
## Install a specific version
To install a specific version of `docker-engine`:
1. List all available versions using `apt-cache madison`:
```bash
$ apt-cache madison docker-engine
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
docker-engine | 1.11.2-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages
docker-engine | 1.11.1-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages
docker-engine | 1.11.0-0~xenial | https://apt.dockerproject.org/repo ubuntu-xenial/main amd64 Packages
```
2. The second field is the version string. To install exactly `1.12.0-0~xenial`,
append it after the package name in the `apt-get install` command, separated
from the package name by an equals sign (`=`).
```bash
$ sudo apt-get install docker-engine=1.12.0-0~xenial
```
If you already have a newer version installed, you will be prompted to
downgrade Docker. Otherwise, the specific version will be installed.
3. Follow steps 4 and 5 of
[Install the latest version](ubuntulinux.md#install-the-latest-version).
## Install a pre-release version
If you want to test Docker on Ubuntu, on a non-production system, follow these
steps. To install a stable released version of Docker afterward, you will need
to revert to the previous configuration.
1. Edit `/etc/apt/sources.list.d/docker.list`.
```bash
$ sudo nano /etc/apt/sources.list.d/docker.list
```
Change `main` to `testing` at the end of the top line. Save and close the
file.
2. Update the package list.
```bash
$ sudo apt-get update
```
3. List the available testing versions.
```bash
$ sudo apt-cache madison docker-engine
```
4. Install a specific version following the same procedure as
[Install a specific version](ubuntulinux.md#install-a-specific-version).
## Optional configurations
This section contains optional procedures for configuring Ubuntu to work better
with Docker.
* [Manage Docker as a non-root user](ubuntulinux.md#manage-docker-as-a-non-root-user)
* [Adjust memory and swap accounting](ubuntulinux.md#adjust-memory-and-swap-accounting)
* [Enable UFW forwarding](ubuntulinux.md#enable-ufw-forwarding)
* [Configure a DNS server for use by Docker](ubuntulinux.md#configure-a-dns-server-for-use-by-docker)
* [Configure Docker to start on boot](ubuntulinux.md#configure-docker-to-start-on-boot)
### 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 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).
To create the `docker` group and add your user:
1. Log into Ubuntu as a user with `sudo` privileges.
2. Create the `docker` group.
```bash
$ sudo groupadd docker
```
3. Add your user to the `docker` group.
```bash
$ sudo usermod -aG docker $USER
```
4. Log out and log back in so that your group membership is re-evaluated.
5. Verify that you can `docker` commands without `sudo`.
```bash
$ docker run hello-world
```
If this fails, you will see an error:
```none
Cannot connect to the Docker daemon. Is 'docker daemon' running on this host?
```
Check whether the `DOCKER_HOST` environment variable is set for your shell.
```bash
$ env | grep DOCKER_HOST
```
If it is set, the above command will return a result. If so, 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.
### Enable memory and swap accounting
You may see messages similar to the following when working with an image:
```none
WARNING: Your kernel does not support cgroup swap limit. WARNING: Your
kernel does not support swap limit capabilities. Limitation discarded.
```
If you don't care about 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.
### Enable UFW forwarding
If you use [UFW (Uncomplicated Firewall)](https://help.ubuntu.com/community/UFW)
on the same host as you run Docker, you'll need to do additional configuration.
Docker uses a bridge to manage container networking. By default, UFW drops all
forwarding traffic. You must set UFW's forwarding policy appropriately.
In addition, UFW blocks 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. Log into Ubuntu as a user with `sudo` privileges.
2. Verify that UFW is enabled.
```bash
$ sudo ufw status
```
If `ufw` is not enabled, the remaining steps will not be helpful.
3. 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.
4. 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
```
5. Reload UFW.
```bash
$ sudo ufw reload
```
### Configure a DNS server for use by Docker
Ubuntu systems which use `networkmanager` use a `dnsmasq` instance that runs on
a loopback address such as `127.0.0.1` or `127.0.1.1` and adds this entry to
`/etc/resolv.conf`. The `dnsmasq` service provides a local DNS cache to speed up
DNS look-ups and also provides DHCP services. This configuration will not work
within a Docker container which has its own network namespace. This is 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 don't use `dnsmasq` or NetworkManager or have never seen this warning,
you can skip the rest of this section. To see if you use `dnsmasq`, use the
following command:
```bash
$ ps aux |grep dnsmasq
```
If this warning occurs and cannot use the public nameservers, such as when you
run a DNS server which resolves hostnames on your internal network, you have
two choices:
- You can specify a DNS server for Docker to use.
- 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 instructions below work whether your Ubuntu installation uses `upstart` or
`systemd`.
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. Log into Ubuntu as a user with `sudo` privileges.
2. 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 my_internal_host
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` in NetworkManager
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
```
### Configure Docker to start on boot
Ubuntu uses `systemd` as its boot and service manager `15.04` onwards and `upstart`
for versions `14.10` and below.
#### `systemd`
```bash
$ sudo systemctl enable docker
```
#### `upstart`
For `14.10` and below, Docker is automatically configured to start on boot using
`upstart`.
## Upgrade Docker
To install the latest version of Docker with `apt-get`. The following example
fetches information about available versions of all system packages, then
updates Docker if a new version is available.
```bash
$ sudo apt-get update
$ sudo apt-get install docker-engine
```
## Uninstallation
To uninstall the Docker package:
```bash
$ sudo apt-get purge docker-engine
```
To uninstall the Docker package and dependencies that are no longer needed:
```bash
$ sudo apt-get autoremove --purge docker-engine
```
Images, containers, volumes, or customized configuration files on your host are
not automatically removed. To delete all images, containers, and volumes run the
following command:
```bash
$ rm -rf /var/lib/docker
```
You must delete any edited configuration files manually.