From cf1781608326e9e3ce090383259bbc26d43c49d6 Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Tue, 21 Jan 2014 01:48:48 +0000 Subject: [PATCH 1/6] docs: simplify basic usage doc, step 1: check your docker install docker-DCO-1.1-Signed-off-by: Solomon Hykes (github: shykes) --- docs/sources/use/basics.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/sources/use/basics.rst b/docs/sources/use/basics.rst index 7d3d8e42a..6ad385130 100644 --- a/docs/sources/use/basics.rst +++ b/docs/sources/use/basics.rst @@ -6,21 +6,22 @@ Learn Basic Commands ==================== -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 have an incomplete +docker installation. Please refer to :ref:`installation_list` for installation +instructions. + Download a pre-built image -------------------------- From cf5504eed50f01797646079ab849260ec16cd5a2 Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Tue, 21 Jan 2014 02:10:32 +0000 Subject: [PATCH 2/6] docs: move a sysadmin-focused topic out of the basic usage manual and into installation docs (setting up a user group for non-root access) docker-DCO-1.1-Signed-off-by: Solomon Hykes (github: shykes) --- docs/sources/installation/binaries.rst | 22 ++++++++++++ docs/sources/installation/ubuntulinux.rst | 38 +++++++++++++++++++- docs/sources/use/basics.rst | 42 ++--------------------- 3 files changed, 62 insertions(+), 40 deletions(-) diff --git a/docs/sources/installation/binaries.rst b/docs/sources/installation/binaries.rst index 611429f84..9b741d691 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 17eee15e9..9019f76c4 100644 --- a/docs/sources/installation/ubuntulinux.rst +++ b/docs/sources/installation/ubuntulinux.rst @@ -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 6ad385130..ed9dafe78 100644 --- a/docs/sources/use/basics.rst +++ b/docs/sources/use/basics.rst @@ -18,10 +18,10 @@ your docker install, run the following command: docker info If you get ``docker: command not found`` or something like -``/var/lib/docker/repositories: permission denied`` you have an incomplete -docker installation. Please refer to :ref:`installation_list` for installation -instructions. +``/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 -------------------------- @@ -52,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 From 76eee50a67732ee18a678ebf54720b78370254df Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Tue, 21 Jan 2014 02:58:04 +0000 Subject: [PATCH 3/6] docs: add standard 'check your docker install' paragraph to the 'hello world' examples. Docker-DCO-1.1-Signed-off-by: Solomon Hykes (github: shykes) --- docs/sources/examples/hello_world.rst | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/sources/examples/hello_world.rst b/docs/sources/examples/hello_world.rst index aeb95881d..57954a98c 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. From 589e1a9bdce47d87870c64c5449002bca2b315a4 Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Tue, 21 Jan 2014 03:31:23 +0000 Subject: [PATCH 4/6] docs: "first steps with docker" is a better title than "learn basic commands" Docker-DCO-1.1-Signed-off-by: Solomon Hykes (github: shykes) --- docs/sources/use/basics.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sources/use/basics.rst b/docs/sources/use/basics.rst index ed9dafe78..cfc5ba4cb 100644 --- a/docs/sources/use/basics.rst +++ b/docs/sources/use/basics.rst @@ -1,10 +1,10 @@ -: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 +======================= Check your docker install ------------------------- From c24d128bb545e292ffb0790d8ad3652f56d62b44 Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Tue, 21 Jan 2014 03:39:33 +0000 Subject: [PATCH 5/6] Docs: move advanced topic "create your own base image" out of basic user guide Docker-DCO-1.1-Signed-off-by: Solomon Hykes (github: shykes) --- docs/sources/{use => articles}/baseimages.rst | 0 docs/sources/articles/index.rst | 1 + docs/sources/use/index.rst | 1 - 3 files changed, 1 insertion(+), 1 deletion(-) rename docs/sources/{use => articles}/baseimages.rst (100%) 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 be01a7af3..708ca3532 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/use/index.rst b/docs/sources/use/index.rst index 23428226a..c1b7691cc 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 From ae2af201f340420f70ca05d54d150764bd88e680 Mon Sep 17 00:00:00 2001 From: Solomon Hykes Date: Tue, 21 Jan 2014 07:26:45 +0000 Subject: [PATCH 6/6] Docs: fix capitalization of "Docker" Docker-DCO-1.1-Signed-off-by: Solomon Hykes (github: shykes) --- docs/sources/examples/hello_world.rst | 6 +++--- docs/sources/installation/ubuntulinux.rst | 4 ++-- docs/sources/use/basics.rst | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/sources/examples/hello_world.rst b/docs/sources/examples/hello_world.rst index 57954a98c..3a6a7b858 100644 --- a/docs/sources/examples/hello_world.rst +++ b/docs/sources/examples/hello_world.rst @@ -9,11 +9,11 @@ Hello World .. _running_examples: -Check your docker install +Check your Docker install ------------------------- This guide assumes you have a working installation of Docker. To check -your docker install, run the following command: +your Docker install, run the following command: .. code-block:: bash @@ -22,7 +22,7 @@ your docker install, run the following 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. +Docker installation or insufficient privileges to access docker on your machine. Please refer to :ref:`installation_list` for installation instructions. diff --git a/docs/sources/installation/ubuntulinux.rst b/docs/sources/installation/ubuntulinux.rst index 9019f76c4..d5e4a248b 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, @@ -199,7 +199,7 @@ client commands. # this to take effect. sudo gpasswd -a ${USER} docker - # Restart the docker daemon. + # Restart the Docker daemon. sudo service docker restart diff --git a/docs/sources/use/basics.rst b/docs/sources/use/basics.rst index cfc5ba4cb..6bd1f0b7a 100644 --- a/docs/sources/use/basics.rst +++ b/docs/sources/use/basics.rst @@ -6,11 +6,11 @@ First steps with Docker ======================= -Check your docker install +Check your Docker install ------------------------- This guide assumes you have a working installation of Docker. To check -your docker install, run the following command: +your Docker install, run the following command: .. code-block:: bash @@ -19,7 +19,7 @@ your docker install, run the following 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. +docker installation or insufficient privileges to access Docker on your machine. Please refer to :ref:`installation_list` for installation instructions.