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> &mdash; refer to note 5 under each version.</p></td> </tr>
    78  <tr> <td class="tg-031">libgl1-mesa-glx-lts-trusty</td> </tr> </table> &nbsp;
    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  &nbsp;
   309  &nbsp;
   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  &nbsp;
   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.