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