basics.rst 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. :title: Basic Commands
  2. :description: Common usage and commands
  3. :keywords: Examples, Usage, basic commands, docker, documentation, examples
  4. The Basics
  5. ==========
  6. Starting Docker
  7. ---------------
  8. If you have used one of the quick install paths', Docker may have been
  9. installed with upstart, Ubuntu's system for starting processes at boot
  10. time. You should be able to run ``sudo docker help`` and get output.
  11. If you get ``docker: command not found`` or something like
  12. ``/var/lib/docker/repositories: permission denied`` you will need to
  13. specify the path to it and manually start it.
  14. .. code-block:: bash
  15. # Run docker in daemon mode
  16. sudo <path to>/docker -d &
  17. Running an interactive shell
  18. ----------------------------
  19. .. code-block:: bash
  20. # Download an ubuntu image
  21. sudo docker pull ubuntu
  22. # Run an interactive shell in the ubuntu image,
  23. # allocate a tty, attach stdin and stdout
  24. # To detach the tty without exiting the shell,
  25. # use the escape sequence Ctrl-p + Ctrl-q
  26. sudo docker run -i -t ubuntu /bin/bash
  27. .. _dockergroup:
  28. Why ``sudo``?
  29. -------------
  30. The ``docker`` daemon always runs as root, and since ``docker``
  31. version 0.5.2, ``docker`` binds to a Unix socket instead of a TCP
  32. port. By default that Unix socket is owned by the user *root*, and so,
  33. by default, you can access it with ``sudo``.
  34. Starting in version 0.5.3, if you create a Unix group called *docker*
  35. and add users to it, then the ``docker`` daemon will make the
  36. ownership of the Unix socket read/writable by the *docker* group when
  37. the daemon starts. The ``docker`` daemon must always run as root, but
  38. if you run the ``docker`` client as a user in the *docker* group then
  39. you don't need to add ``sudo`` to all the client commands.
  40. .. code-block:: bash
  41. # Add the docker group
  42. sudo groupadd docker
  43. # Add the ubuntu user to the docker group
  44. # You may have to logout and log back in again for
  45. # this to take effect
  46. sudo gpasswd -a ubuntu docker
  47. # Restart the docker daemon
  48. sudo service docker restart
  49. Bind Docker to another host/port or a Unix socket
  50. -------------------------------------------------
  51. .. DANGER:: Changing the default ``docker`` daemon binding to a TCP
  52. port or Unix *docker* user group will increase your security risks
  53. by allowing non-root users to potentially gain *root* access on the
  54. host (`e.g. #1369
  55. <https://github.com/dotcloud/docker/issues/1369>`_). Make sure you
  56. control access to ``docker``.
  57. With -H it is possible to make the Docker daemon to listen on a
  58. specific ip and port. By default, it will listen on
  59. ``unix:///var/run/docker.sock`` to allow only local connections by the
  60. *root* user. You *could* set it to 0.0.0.0:4243 or a specific host ip to
  61. give access to everybody, but that is **not recommended** because then
  62. it is trivial for someone to gain root access to the host where the
  63. daemon is running.
  64. Similarly, the Docker client can use ``-H`` to connect to a custom port.
  65. ``-H`` accepts host and port assignment in the following format:
  66. ``tcp://[host][:port]`` or ``unix://path``
  67. For example:
  68. * ``tcp://host:4243`` -> tcp connection on host:4243
  69. * ``unix://path/to/socket`` -> unix socket located at ``path/to/socket``
  70. .. code-block:: bash
  71. # Run docker in daemon mode
  72. sudo <path to>/docker -H 0.0.0.0:5555 -d &
  73. # Download an ubuntu image
  74. sudo docker -H :5555 pull ubuntu
  75. You can use multiple ``-H``, for example, if you want to listen on
  76. both TCP and a Unix socket
  77. .. code-block:: bash
  78. # Run docker in daemon mode
  79. sudo <path to>/docker -H tcp://127.0.0.1:4243 -H unix:///var/run/docker.sock -d &
  80. # Download an ubuntu image, use default Unix socket
  81. sudo docker pull ubuntu
  82. # OR use the TCP port
  83. sudo docker -H tcp://127.0.0.1:4243 pull ubuntu
  84. Starting a long-running worker process
  85. --------------------------------------
  86. .. code-block:: bash
  87. # Start a very useful long-running process
  88. JOB=$(sudo docker run -d ubuntu /bin/sh -c "while true; do echo Hello world; sleep 1; done")
  89. # Collect the output of the job so far
  90. sudo docker logs $JOB
  91. # Kill the job
  92. sudo docker kill $JOB
  93. Listing all running containers
  94. ------------------------------
  95. .. code-block:: bash
  96. sudo docker ps
  97. Expose a service on a TCP port
  98. ------------------------------
  99. .. code-block:: bash
  100. # Expose port 4444 of this container, and tell netcat to listen on it
  101. JOB=$(sudo docker run -d -p 4444 ubuntu /bin/nc -l -p 4444)
  102. # Which public port is NATed to my container?
  103. PORT=$(sudo docker port $JOB 4444)
  104. # Connect to the public port via the host's public address
  105. # Please note that because of how routing works connecting to localhost or 127.0.0.1 $PORT will not work.
  106. # Replace *eth0* according to your local interface name.
  107. IP=$(ip -o -4 addr list eth0 | perl -n -e 'if (m{inet\s([\d\.]+)\/\d+\s}xms) { print $1 }')
  108. echo hello world | nc $IP $PORT
  109. # Verify that the network connection worked
  110. echo "Daemon received: $(sudo docker logs $JOB)"
  111. Committing (saving) a container state
  112. -------------------------------------
  113. Save your containers state to a container image, so the state can be re-used.
  114. When you commit your container only the differences between the image
  115. the container was created from and the current state of the container
  116. will be stored (as a diff). See which images you already have using
  117. ``sudo docker images``
  118. .. code-block:: bash
  119. # Commit your container to a new named image
  120. sudo docker commit <container_id> <some_name>
  121. # List your containers
  122. sudo docker images
  123. You now have a image state from which you can create new instances.
  124. Read more about :ref:`working_with_the_repository` or continue to the
  125. complete :ref:`cli`