github.com/portworx/docker@v1.12.1/docs/installation/linux/ubuntulinux.md (about) 1 <!--[metadata]> 2 +++ 3 aliases = [ "/engine/installation/ubuntulinux/"] 4 title = "Installation on Ubuntu " 5 description = "Instructions for installing Docker on Ubuntu. " 6 keywords = ["Docker, Docker documentation, requirements, apt, installation, ubuntu"] 7 [menu.main] 8 parent = "engine_linux" 9 weight = -6 10 +++ 11 <![end-metadata]--> 12 13 # Ubuntu 14 15 Docker is supported on these Ubuntu operating systems: 16 17 - Ubuntu Xenial 16.04 (LTS) 18 - Ubuntu Wily 15.10 19 - Ubuntu Trusty 14.04 (LTS) 20 - Ubuntu Precise 12.04 (LTS) 21 22 This page instructs you to install using Docker-managed release packages and 23 installation mechanisms. Using these packages ensures you get the latest release 24 of Docker. If you wish to install using Ubuntu-managed packages, consult your 25 Ubuntu documentation. 26 27 >**Note**: Ubuntu Utopic 14.10 and 15.04 exist in Docker's `APT` repository but 28 > are no longer officially supported. 29 30 ## Prerequisites 31 32 Docker requires a 64-bit installation regardless of your Ubuntu version. 33 Additionally, your kernel must be 3.10 at minimum. The latest 3.10 minor version 34 or a newer maintained version are also acceptable. 35 36 Kernels older than 3.10 lack some of the features required to run Docker 37 containers. These older versions are known to have bugs which cause data loss 38 and frequently panic under certain conditions. 39 40 To check your current kernel version, open a terminal and use `uname -r` to 41 display your kernel version: 42 43 $ uname -r 44 3.11.0-15-generic 45 46 >**Note**: If you previously installed Docker using `APT`, make sure you update 47 your `APT` sources to the new Docker repository. 48 49 ### Update your apt sources 50 51 Docker's `APT` repository contains Docker 1.7.1 and higher. To set `APT` to use 52 packages from the new repository: 53 54 1. Log into your machine as a user with `sudo` or `root` privileges. 55 56 2. Open a terminal window. 57 58 3. Update package information, ensure that APT works with the `https` method, and that CA certificates are installed. 59 60 $ sudo apt-get update 61 $ sudo apt-get install apt-transport-https ca-certificates 62 63 4. Add the new `GPG` key. 64 65 $ sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D 66 67 5. Open the `/etc/apt/sources.list.d/docker.list` file in your favorite editor. 68 69 If the file doesn't exist, create it. 70 71 6. Remove any existing entries. 72 73 7. Add an entry for your Ubuntu operating system. 74 75 The possible entries are: 76 77 - On Ubuntu Precise 12.04 (LTS) 78 79 deb https://apt.dockerproject.org/repo ubuntu-precise main 80 81 - On Ubuntu Trusty 14.04 (LTS) 82 83 deb https://apt.dockerproject.org/repo ubuntu-trusty main 84 85 - Ubuntu Wily 15.10 86 87 deb https://apt.dockerproject.org/repo ubuntu-wily main 88 89 - Ubuntu Xenial 16.04 (LTS) 90 91 deb https://apt.dockerproject.org/repo ubuntu-xenial main 92 93 > **Note**: Docker does not provide packages for all architectures. You can find 94 > nightly built binaries in https://master.dockerproject.org. To install docker on 95 > a multi-architecture system, add an `[arch=...]` clause to the entry. Refer to the 96 > [Debian Multiarch wiki](https://wiki.debian.org/Multiarch/HOWTO#Setting_up_apt_sources) 97 > for details. 98 99 8. Save and close the `/etc/apt/sources.list.d/docker.list` file. 100 101 9. Update the `APT` package index. 102 103 $ sudo apt-get update 104 105 10. Purge the old repo if it exists. 106 107 $ sudo apt-get purge lxc-docker 108 109 11. Verify that `APT` is pulling from the right repository. 110 111 $ apt-cache policy docker-engine 112 113 From now on when you run `apt-get upgrade`, `APT` pulls from the new repository. 114 115 ### Prerequisites by Ubuntu Version 116 117 - Ubuntu Xenial 16.04 (LTS) 118 - Ubuntu Wily 15.10 119 - Ubuntu Trusty 14.04 (LTS) 120 121 For Ubuntu Trusty, Wily, and Xenial, it's recommended to install the 122 `linux-image-extra-*` kernel packages. The `linux-image-extra-*` packages 123 allows you use the `aufs` storage driver. 124 125 To install the `linux-image-extra-*` packages: 126 127 1. Open a terminal on your Ubuntu host. 128 129 2. Update your package manager. 130 131 $ sudo apt-get update 132 133 3. Install the recommended packages. 134 135 $ sudo apt-get install linux-image-extra-$(uname -r) linux-image-extra-virtual 136 137 4. Go ahead and install Docker. 138 139 #### Ubuntu Precise 12.04 (LTS) 140 141 For Ubuntu Precise, Docker requires the 3.13 kernel version. If your kernel 142 version is older than 3.13, you must upgrade it. Refer to this table to see 143 which packages are required for your environment: 144 145 <style type="text/css"> .tg {border-collapse:collapse;border-spacing:0;} .tg 146 td{font-size:14px;padding:10px 147 5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;} 148 .tg-031{width:275px;font-family:monospace} </style> <table class="tg"> <tr> <td 149 class="tg-031">linux-image-generic-lts-trusty</td> <td class="tg-031e">Generic 150 Linux kernel image. This kernel has AUFS built in. This is required to run 151 Docker.</td> </tr> <tr> <td class="tg-031">linux-headers-generic-lts-trusty</td> 152 <td class="tg-031e">Allows packages such as ZFS and VirtualBox guest additions 153 which depend on them. If you didn't install the headers for your existing 154 kernel, then you can skip these headers for the"trusty" kernel. If you're 155 unsure, you should include this package for safety.</td> </tr> <tr> <td 156 class="tg-031">xserver-xorg-lts-trusty</td> <td class="tg-031e" 157 rowspan="2">Optional in non-graphical environments without Unity/Xorg. 158 <b>Required</b> when running Docker on machine with a graphical environment. 159 <br> 160 <br>To learn more about the reasons for these packages, read the installation 161 instructions for backported kernels, specifically the <a 162 href="https://wiki.ubuntu.com/Kernel/LTSEnablementStack" target="_blank">LTS 163 Enablement Stack</a> — refer to note 5 under each version. 164 </td> </tr> 165 <tr> <td class="tg-031">libgl1-mesa-glx-lts-trusty</td> </tr> </table> 166 167 To upgrade your kernel and install the additional packages, do the following: 168 169 1. Open a terminal on your Ubuntu host. 170 171 2. Update your package manager. 172 173 $ sudo apt-get update 174 175 3. Install both the required and optional packages. 176 177 $ sudo apt-get install linux-image-generic-lts-trusty 178 179 Depending on your environment, you may install more as described in the preceding table. 180 181 4. Reboot your host. 182 183 $ sudo reboot 184 185 5. After your system reboots, go ahead and install Docker. 186 187 ## Install 188 189 Make sure you have installed the prerequisites for your Ubuntu version. 190 191 Then, 192 install Docker using the following: 193 194 1. Log into your Ubuntu installation as a user with `sudo` privileges. 195 196 2. Update your `APT` package index. 197 198 $ sudo apt-get update 199 200 3. Install Docker. 201 202 $ sudo apt-get install docker-engine 203 204 4. Start the `docker` daemon. 205 206 $ sudo service docker start 207 208 5. Verify `docker` is installed correctly. 209 210 $ sudo docker run hello-world 211 212 This command downloads a test image and runs it in a container. When the 213 container runs, it prints an informational message. Then, it exits. 214 215 ## Optional configurations 216 217 This section contains optional procedures for configuring your Ubuntu to work 218 better with Docker. 219 220 * [Create a docker group](#create-a-docker-group) 221 * [Adjust memory and swap accounting](#adjust-memory-and-swap-accounting) 222 * [Enable UFW forwarding](#enable-ufw-forwarding) 223 * [Configure a DNS server for use by Docker](#configure-a-dns-server-for-use-by-docker) 224 * [Configure Docker to start on boot](#configure-docker-to-start-on-boot) 225 226 ### Create a Docker group 227 228 The `docker` daemon binds to a Unix socket instead of a TCP port. By default 229 that Unix socket is owned by the user `root` and other users can access it with 230 `sudo`. For this reason, `docker` daemon always runs as the `root` user. 231 232 To avoid having to use `sudo` when you use the `docker` command, create a Unix 233 group called `docker` and add users to it. When the `docker` daemon starts, it 234 makes the ownership of the Unix socket read/writable by the `docker` group. 235 236 >**Warning**: The `docker` group is equivalent to the `root` user; For details 237 >on how this impacts security in your system, see [*Docker Daemon Attack 238 >Surface*](../../security/security.md#docker-daemon-attack-surface) for details. 239 240 To create the `docker` group and add your user: 241 242 1. Log into Ubuntu as a user with `sudo` privileges. 243 244 2. Create the `docker` group. 245 246 $ sudo groupadd docker 247 248 3. Add your user to `docker` group. 249 250 $ sudo usermod -aG docker $USER 251 252 4. Log out and log back in. 253 254 This ensures your user is running with the correct permissions. 255 256 5. Verify your work by running `docker` without `sudo`. 257 258 $ docker run hello-world 259 260 If this fails with a message similar to this: 261 262 Cannot connect to the Docker daemon. Is 'docker daemon' running on this host? 263 264 Check that the `DOCKER_HOST` environment variable is not set for your shell. 265 If it is, unset it. 266 267 ### Adjust memory and swap accounting 268 269 When users run Docker, they may see these messages when working with an image: 270 271 WARNING: Your kernel does not support cgroup swap limit. WARNING: Your 272 kernel does not support swap limit capabilities. Limitation discarded. 273 274 To prevent these messages, enable memory and swap accounting on your 275 system. Enabling memory and swap accounting does induce both a memory 276 overhead and a performance degradation even when Docker is not in 277 use. The memory overhead is about 1% of the total available 278 memory. The performance degradation is roughly 10%. 279 280 To enable memory and swap on system using GNU GRUB (GNU GRand Unified 281 Bootloader), do the following: 282 283 1. Log into Ubuntu as a user with `sudo` privileges. 284 285 2. Edit the `/etc/default/grub` file. 286 287 3. Set the `GRUB_CMDLINE_LINUX` value as follows: 288 289 GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1" 290 291 4. Save and close the file. 292 293 5. Update GRUB. 294 295 $ sudo update-grub 296 297 6. Reboot your system. 298 299 300 ### Enable UFW forwarding 301 302 If you use [UFW (Uncomplicated Firewall)](https://help.ubuntu.com/community/UFW) 303 on the same host as you run Docker, you'll need to do additional configuration. 304 Docker uses a bridge to manage container networking. By default, UFW drops all 305 forwarding traffic. As a result, for Docker to run when UFW is 306 enabled, you must set UFW's forwarding policy appropriately. 307 308 Also, UFW's default set of rules denies all incoming traffic. If you want to 309 reach your containers from another host allow incoming connections on the Docker 310 port. The Docker port defaults to `2376` if TLS is enabled or `2375` when it is 311 not. If TLS is not enabled, communication is unencrypted. By default, Docker 312 runs without TLS enabled. 313 314 To configure UFW and allow incoming connections on the Docker port: 315 316 1. Log into Ubuntu as a user with `sudo` privileges. 317 318 2. Verify that UFW is installed and enabled. 319 320 $ sudo ufw status 321 322 3. Open the `/etc/default/ufw` file for editing. 323 324 $ sudo nano /etc/default/ufw 325 326 4. Set the `DEFAULT_FORWARD_POLICY` policy to: 327 328 DEFAULT_FORWARD_POLICY="ACCEPT" 329 330 5. Save and close the file. 331 332 6. Reload UFW to use the new setting. 333 334 $ sudo ufw reload 335 336 7. Allow incoming connections on the Docker port. 337 338 $ sudo ufw allow 2375/tcp 339 340 ### Configure a DNS server for use by Docker 341 342 Systems that run Ubuntu or an Ubuntu derivative on the desktop typically use 343 `127.0.0.1` as the default `nameserver` in `/etc/resolv.conf` file. The 344 NetworkManager also sets up `dnsmasq` to use the real DNS servers of the 345 connection and sets up `nameserver 127.0.0.1` in /`etc/resolv.conf`. 346 347 When starting containers on desktop machines with these configurations, Docker 348 users see this warning: 349 350 WARNING: Local (127.0.0.1) DNS resolver found in resolv.conf and containers 351 can't use it. Using default external servers : [8.8.8.8 8.8.4.4] 352 353 The warning occurs because Docker containers can't use the local DNS nameserver. 354 Instead, Docker defaults to using an external nameserver. 355 356 To avoid this warning, you can specify a DNS server for use by Docker 357 containers. Or, you can disable `dnsmasq` in NetworkManager. Though, disabling 358 `dnsmasq` might make DNS resolution slower on some networks. 359 360 The instructions below describe how to configure the Docker daemon 361 running on Ubuntu 14.10 or below. Ubuntu 15.04 and above use `systemd` 362 as the boot and service manager. Refer to [control and configure Docker 363 with systemd](../../admin/systemd.md#custom-docker-daemon-options) to 364 configure a daemon controlled by `systemd`. 365 366 To specify a DNS server for use by Docker: 367 368 1. Log into Ubuntu as a user with `sudo` privileges. 369 370 2. Open the `/etc/default/docker` file for editing. 371 372 $ sudo nano /etc/default/docker 373 374 3. Add a setting for Docker. 375 376 DOCKER_OPTS="--dns 8.8.8.8" 377 378 Replace `8.8.8.8` with a local DNS server such as `192.168.1.1`. You can also 379 specify multiple DNS servers. Separated them with spaces, for example: 380 381 --dns 8.8.8.8 --dns 192.168.1.1 382 383 >**Warning**: If you're doing this on a laptop which connects to various 384 >networks, make sure to choose a public DNS server. 385 386 4. Save and close the file. 387 388 5. Restart the Docker daemon. 389 390 $ sudo service docker restart 391 392 393 394 395 396 **Or, as an alternative to the previous procedure,** disable `dnsmasq` in 397 NetworkManager (this might slow your network). 398 399 1. Open the `/etc/NetworkManager/NetworkManager.conf` file for editing. 400 401 $ sudo nano /etc/NetworkManager/NetworkManager.conf 402 403 2. Comment out the `dns=dnsmasq` line: 404 405 dns=dnsmasq 406 407 3. Save and close the file. 408 409 4. Restart both the NetworkManager and Docker. 410 411 $ sudo restart network-manager 412 $ sudo restart docker 413 414 ### Configure Docker to start on boot 415 416 Ubuntu uses `systemd` as its boot and service manager `15.04` onwards and `upstart` 417 for versions `14.10` and below. 418 419 For `15.04` and up, to configure the `docker` daemon to start on boot, run 420 421 $ sudo systemctl enable docker 422 423 For `14.10` and below the above installation method automatically configures `upstart` 424 to start the docker daemon on boot 425 426 ## Upgrade Docker 427 428 To install the latest version of Docker with `apt-get`: 429 430 $ sudo apt-get upgrade docker-engine 431 432 ## Uninstallation 433 434 To uninstall the Docker package: 435 436 $ sudo apt-get purge docker-engine 437 438 To uninstall the Docker package and dependencies that are no longer needed: 439 440 $ sudo apt-get autoremove --purge docker-engine 441 442 The above commands will not remove images, containers, volumes, or user created 443 configuration files on your host. If you wish to delete all images, containers, 444 and volumes run the following command: 445 446 $ rm -rf /var/lib/docker 447 448 You must delete the user created configuration files manually.