Merge pull request #3688 from shykes/docs-simplify-basic-usage

Simplify basic usage docs

docs/sources/articles/index.rst

@@ -10,3 +10,4 @@ Contents:
    :maxdepth: 1
 
    security
+   baseimages

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
-
-   sudo docker help
+Please refer to :ref:`installation_list` for installation instructions.
 
-----
 
 .. _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.
 

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
 --------
 

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:

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 <path to>/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

docs/sources/use/index.rst

@@ -14,7 +14,6 @@ Contents:
 
    basics
    workingwithrepository
-   baseimages
    port_redirection
    networking
    host_integration