diff --git a/docs/sources/use/baseimages.rst b/docs/sources/articles/baseimages.rst similarity index 100% rename from docs/sources/use/baseimages.rst rename to docs/sources/articles/baseimages.rst diff --git a/docs/sources/articles/index.rst b/docs/sources/articles/index.rst index be01a7af32..708ca35326 100644 --- a/docs/sources/articles/index.rst +++ b/docs/sources/articles/index.rst @@ -10,3 +10,4 @@ Contents: :maxdepth: 1 security + baseimages diff --git a/docs/sources/examples/hello_world.rst b/docs/sources/examples/hello_world.rst index aeb95881d2..3a6a7b8587 100644 --- a/docs/sources/examples/hello_world.rst +++ b/docs/sources/examples/hello_world.rst @@ -9,25 +9,23 @@ Hello World .. _running_examples: -Running the Examples -==================== +Check your Docker install +------------------------- -All the examples assume your machine is running the ``docker`` daemon. To -run the ``docker`` daemon in the background, simply type: +This guide assumes you have a working installation of Docker. To check +your Docker install, run the following command: .. code-block:: bash - sudo docker -d & + # Check that you have a working install + docker info -Now you can run Docker in client mode: by default all commands will be -forwarded to the ``docker`` daemon via a protected Unix socket, so you -must run as the ``root`` or via the ``sudo`` command. +If you get ``docker: command not found`` or something like +``/var/lib/docker/repositories: permission denied`` you may have an incomplete +Docker installation or insufficient privileges to access docker on your machine. -.. code-block:: bash +Please refer to :ref:`installation_list` for installation instructions. - sudo docker help - ----- .. _hello_world: @@ -88,9 +86,7 @@ Hello World Daemon And now for the most boring daemon ever written! -This example assumes you have Docker installed and the Ubuntu -image already imported with ``docker pull ubuntu``. We will use the Ubuntu -image to run a simple hello world daemon that will just print hello +We will use the Ubuntu image to run a simple hello world daemon that will just print hello world to standard out every second. It will continue to do this until we stop it. diff --git a/docs/sources/installation/binaries.rst b/docs/sources/installation/binaries.rst index 611429f84a..9b741d6918 100644 --- a/docs/sources/installation/binaries.rst +++ b/docs/sources/installation/binaries.rst @@ -57,6 +57,28 @@ Run the docker daemon # start the docker in daemon mode from the directory you unpacked sudo ./docker -d & + +.. _dockergroup: + +Giving non-root access +---------------------- + +The ``docker`` daemon always runs as the root user, and since Docker version +0.5.2, 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``. + +Starting in version 0.5.3, 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. + +.. warning:: The *docker* group is root-equivalent. + + Upgrades -------- diff --git a/docs/sources/installation/ubuntulinux.rst b/docs/sources/installation/ubuntulinux.rst index 17eee15e9a..d5e4a248ba 100644 --- a/docs/sources/installation/ubuntulinux.rst +++ b/docs/sources/installation/ubuntulinux.rst @@ -35,7 +35,7 @@ Dependencies **Linux kernel 3.8** -Due to a bug in LXC, docker works best on the 3.8 kernel. Precise +Due to a bug in LXC, Docker works best on the 3.8 kernel. Precise comes with a 3.2 kernel, so we need to upgrade it. The kernel you'll install when following these steps comes with AUFS built in. We also include the generic headers to enable packages that depend on them, @@ -167,7 +167,43 @@ Type ``exit`` to exit **Done!**, now continue with the :ref:`hello_world` example. -Upgrades + +Giving non-root access +---------------------- + +The ``docker`` daemon always runs as the root user, and since Docker version +0.5.2, 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``. + +Starting in version 0.5.3, 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. + +.. warning:: The *docker* group is root-equivalent. + +**Example:** + +.. code-block:: bash + + # 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 -------- To install the latest version of docker, use the standard ``apt-get`` method: diff --git a/docs/sources/use/basics.rst b/docs/sources/use/basics.rst index 7d3d8e42af..6bd1f0b7a0 100644 --- a/docs/sources/use/basics.rst +++ b/docs/sources/use/basics.rst @@ -1,26 +1,27 @@ -:title: Learn Basic Commands +:title: First steps with Docker :description: Common usage and commands :keywords: Examples, Usage, basic commands, docker, documentation, examples -Learn Basic Commands -==================== +First steps with Docker +======================= -Starting Docker ---------------- +Check your Docker install +------------------------- -If you have used one of the quick install paths, Docker may have been -installed with upstart, Ubuntu's system for starting processes at boot -time. You should be able to run ``sudo docker help`` and get output. - -If you get ``docker: command not found`` or something like -``/var/lib/docker/repositories: permission denied`` you will need to -specify the path to it and manually start it. +This guide assumes you have a working installation of Docker. To check +your Docker install, run the following command: .. code-block:: bash - # Run docker in daemon mode - sudo /docker -d & + # Check that you have a working install + docker info + +If you get ``docker: command not found`` or something like +``/var/lib/docker/repositories: permission denied`` you may have an incomplete +docker installation or insufficient privileges to access Docker on your machine. + +Please refer to :ref:`installation_list` for installation instructions. Download a pre-built image -------------------------- @@ -51,42 +52,6 @@ Running an interactive shell # use the escape sequence Ctrl-p + Ctrl-q sudo docker run -i -t ubuntu /bin/bash -.. _dockergroup: - -The sudo command and the docker Group -------------------------------------- - -The ``docker`` daemon always runs as the root user, and since Docker version -0.5.2, 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``. - -Starting in version 0.5.3, 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. - -.. warning:: The *docker* group is root-equivalent. - -**Example:** - -.. code-block:: bash - - # 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 - .. _bind_docker: Bind Docker to another host/port or a Unix socket diff --git a/docs/sources/use/index.rst b/docs/sources/use/index.rst index 23428226a7..c1b7691cca 100644 --- a/docs/sources/use/index.rst +++ b/docs/sources/use/index.rst @@ -14,7 +14,6 @@ Contents: basics workingwithrepository - baseimages port_redirection networking host_integration