basics.rst 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  1. :title: First steps with Docker
  2. :description: Common usage and commands
  3. :keywords: Examples, Usage, basic commands, docker, documentation, examples
  4. First steps with Docker
  5. =======================
  6. Check your Docker install
  7. -------------------------
  8. This guide assumes you have a working installation of Docker. To check
  9. your Docker install, run the following command:
  10. .. code-block:: bash
  11. # Check that you have a working install
  12. docker info
  13. If you get ``docker: command not found`` or something like
  14. ``/var/lib/docker/repositories: permission denied`` you may have an incomplete
  15. docker installation or insufficient privileges to access Docker on your machine.
  16. Please refer to :ref:`installation_list` for installation instructions.
  17. Download a pre-built image
  18. --------------------------
  19. .. code-block:: bash
  20. # Download an ubuntu image
  21. sudo docker pull ubuntu
  22. This will find the ``ubuntu`` image by name in the :ref:`Central Index
  23. <searching_central_index>` and download it from the top-level Central
  24. Repository to a local image cache.
  25. .. NOTE:: When the image has successfully downloaded, you will see a
  26. 12 character hash ``539c0211cd76: Download complete`` which is the
  27. short form of the image ID. These short image IDs are the first 12
  28. characters of the full image ID - which can be found using ``docker
  29. inspect`` or ``docker images -notrunc=true``
  30. Running an interactive shell
  31. ----------------------------
  32. .. code-block:: bash
  33. # Run an interactive shell in the ubuntu image,
  34. # allocate a tty, attach stdin and stdout
  35. # To detach the tty without exiting the shell,
  36. # use the escape sequence Ctrl-p + Ctrl-q
  37. sudo docker run -i -t ubuntu /bin/bash
  38. .. _bind_docker:
  39. Bind Docker to another host/port or a Unix socket
  40. -------------------------------------------------
  41. .. warning:: Changing the default ``docker`` daemon binding to a TCP
  42. port or Unix *docker* user group will increase your security risks
  43. by allowing non-root users to potentially gain *root* access on the
  44. host (`e.g. #1369
  45. <https://github.com/dotcloud/docker/issues/1369>`_). Make sure you
  46. control access to ``docker``.
  47. With ``-H`` it is possible to make the Docker daemon to listen on a
  48. specific IP and port. By default, it will listen on
  49. ``unix:///var/run/docker.sock`` to allow only local connections by the
  50. *root* user. You *could* set it to ``0.0.0.0:4243`` or a specific host IP to
  51. give access to everybody, but that is **not recommended** because then
  52. it is trivial for someone to gain root access to the host where the
  53. daemon is running.
  54. Similarly, the Docker client can use ``-H`` to connect to a custom port.
  55. ``-H`` accepts host and port assignment in the following format:
  56. ``tcp://[host][:port]`` or ``unix://path``
  57. For example:
  58. * ``tcp://host:4243`` -> tcp connection on host:4243
  59. * ``unix://path/to/socket`` -> unix socket located at ``path/to/socket``
  60. ``-H``, when empty, will default to the same value as when no ``-H`` was passed in.
  61. ``-H`` also accepts short form for TCP bindings:
  62. ``host[:port]`` or ``:port``
  63. .. code-block:: bash
  64. # Run docker in daemon mode
  65. sudo <path to>/docker -H 0.0.0.0:5555 -d &
  66. # Download an ubuntu image
  67. sudo docker -H :5555 pull ubuntu
  68. You can use multiple ``-H``, for example, if you want to listen on
  69. both TCP and a Unix socket
  70. .. code-block:: bash
  71. # Run docker in daemon mode
  72. sudo <path to>/docker -H tcp://127.0.0.1:4243 -H unix:///var/run/docker.sock -d &
  73. # Download an ubuntu image, use default Unix socket
  74. sudo docker pull ubuntu
  75. # OR use the TCP port
  76. sudo docker -H tcp://127.0.0.1:4243 pull ubuntu
  77. Starting a long-running worker process
  78. --------------------------------------
  79. .. code-block:: bash
  80. # Start a very useful long-running process
  81. JOB=$(sudo docker run -d ubuntu /bin/sh -c "while true; do echo Hello world; sleep 1; done")
  82. # Collect the output of the job so far
  83. sudo docker logs $JOB
  84. # Kill the job
  85. sudo docker kill $JOB
  86. Listing all running containers
  87. ------------------------------
  88. .. code-block:: bash
  89. sudo docker ps
  90. Bind a service on a TCP port
  91. ------------------------------
  92. .. code-block:: bash
  93. # Bind port 4444 of this container, and tell netcat to listen on it
  94. JOB=$(sudo docker run -d -p 4444 ubuntu:12.10 /bin/nc -l 4444)
  95. # Which public port is NATed to my container?
  96. PORT=$(sudo docker port $JOB 4444 | awk -F: '{ print $2 }')
  97. # Connect to the public port
  98. echo hello world | nc 127.0.0.1 $PORT
  99. # Verify that the network connection worked
  100. echo "Daemon received: $(sudo docker logs $JOB)"
  101. Committing (saving) a container state
  102. -------------------------------------
  103. Save your containers state to a container image, so the state can be re-used.
  104. When you commit your container only the differences between the image the
  105. container was created from and the current state of the container will be
  106. stored (as a diff). See which images you already have using the ``docker
  107. images`` command.
  108. .. code-block:: bash
  109. # Commit your container to a new named image
  110. sudo docker commit <container_id> <some_name>
  111. # List your containers
  112. sudo docker images
  113. You now have a image state from which you can create new instances.
  114. Read more about :ref:`working_with_the_repository` or continue to the
  115. complete :ref:`cli`