Initial commit

vendor/github.com/hyperhq/hypercli/docs/quickstart.md

@@ -0,0 +1,201 @@
+<!--[metadata]>
++++
+aliases = ["/engine/userguide/basics/"]
+title = "Quickstart containers"
+description = "Common usage and commands"
+keywords = ["Examples, Usage, basic commands, docker, documentation,  examples"]
+[menu.main]
+parent = "engine_use"
+weight=-90
++++
+<![end-metadata]-->
+
+# Quickstart Docker Engine
+
+This quickstart assumes you have a working installation of Docker Engine. To verify Engine is installed, use the following command:
+
+    # 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
+Engine on your machine. With the default installation of Engine `docker`
+commands need to be run by a user that is in the `docker` group or by the
+`root` user.
+
+Depending on your Engine system configuration, you may be required
+to preface each `docker` command with `sudo`. One way to avoid having to use
+`sudo` with the `docker` commands is to create a Unix group called `docker` and
+add users that will be entering `docker` commands to the 'docker' group.
+
+For more information about installing Docker Engine or `sudo` configuration, refer to
+the [installation](installation/index.md) instructions for your operating system.
+
+
+## Download a pre-built image
+
+    # Download an ubuntu image
+    $ docker pull ubuntu
+
+This will find the `ubuntu` image by name on
+[*Docker Hub*](userguide/containers/dockerrepos.md#searching-for-images)
+and download it from [Docker Hub](https://hub.docker.com) to a local
+image cache.
+
+> **Note**:
+> When the image is successfully downloaded, you see a 12 character
+> hash `539c0211cd76: Download complete` which is the
+> short form of the image ID. These short image IDs are the first 12
+> characters of the full image ID - which can be found using
+> `docker inspect` or `docker images --no-trunc=true`.
+
+## Running an interactive shell
+
+To run an interactive shell in the Ubuntu image:
+
+    $ docker run -i -t ubuntu /bin/bash       
+
+The `-i` flag starts an interactive container. The `-t` flag creates a
+pseudo-TTY that attaches `stdin` and `stdout`.  
+
+To detach the `tty` without exiting the shell, use the escape sequence
+`Ctrl-p` + `Ctrl-q`. The container will continue to exist in a stopped state
+once exited. To list all containers, stopped and running, use the `docker ps -a`
+command.
+
+## Bind Docker to another host/port or a Unix socket
+
+> **Warning**:
+> Changing the default `docker` daemon binding to a
+> TCP port or Unix *docker* user group will increase your security risks
+> by allowing non-root users to gain *root* access on the host. Make sure
+> you control access to `docker`. If you are binding
+> to a TCP port, anyone with access to that port has full Docker access;
+> so it is not advisable on an open network.
+
+With `-H` it is possible to make the Docker daemon to listen on a
+specific IP and port. By default, it will listen on
+`unix:///var/run/docker.sock` to allow only local connections by the
+*root* user. You *could* set it to `0.0.0.0:2375` or a specific host IP
+to give access to everybody, but that is **not recommended** because
+then it is trivial for someone to gain root access to the host where the
+daemon is running.
+
+Similarly, the Docker client can use `-H` to connect to a custom port.
+The Docker client will default to connecting to `unix:///var/run/docker.sock`
+on Linux, and `tcp://127.0.0.1:2376` on Windows.
+
+`-H` accepts host and port assignment in the following format:
+
+    tcp://[host]:[port][path] or unix://path
+
+For example:
+
+-   `tcp://` -> TCP connection to `127.0.0.1` on either port `2376` when TLS encryption
+    is on, or port `2375` when communication is in plain text.
+-   `tcp://host:2375` -> TCP connection on
+    host:2375
+-   `tcp://host:2375/path` -> TCP connection on
+    host:2375 and prepend path to all requests
+-   `unix://path/to/socket` -> Unix socket located
+    at `path/to/socket`
+
+`-H`, when empty, will default to the same value as
+when no `-H` was passed in.
+
+`-H` also accepts short form for TCP bindings:
+
+    `host:` or `host:port` or `:port`
+
+Run Docker in daemon mode:
+
+    $ sudo <path to>/docker daemon -H 0.0.0.0:5555 &
+
+Download an `ubuntu` image:
+
+    $ docker -H :5555 pull ubuntu
+
+You can use multiple `-H`, for example, if you want to listen on both
+TCP and a Unix socket
+
+    # Run docker in daemon mode
+    $ sudo <path to>/docker daemon -H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock &
+    # Download an ubuntu image, use default Unix socket
+    $ docker pull ubuntu
+    # OR use the TCP port
+    $ docker -H tcp://127.0.0.1:2375 pull ubuntu
+
+## Starting a long-running worker process
+
+    # Start a very useful long-running process
+    $ JOB=$(docker run -d ubuntu /bin/sh -c "while true; do echo Hello world; sleep 1; done")
+
+    # Collect the output of the job so far
+    $ docker logs $JOB
+
+    # Kill the job
+    $ docker kill $JOB
+
+## Listing containers
+
+    $ docker ps # Lists only running containers
+    $ docker ps -a # Lists all containers
+
+## Controlling containers
+
+    # Start a new container
+    $ JOB=$(docker run -d ubuntu /bin/sh -c "while true; do echo Hello world; sleep 1; done")
+
+    # Stop the container
+    $ docker stop $JOB
+
+    # Start the container
+    $ docker start $JOB
+
+    # Restart the container
+    $ docker restart $JOB
+
+    # SIGKILL a container
+    $ docker kill $JOB
+
+    # Remove a container
+    $ docker stop $JOB # Container must be stopped to remove it
+    $ docker rm $JOB
+
+## Bind a service on a TCP port
+
+    # Bind port 4444 of this container, and tell netcat to listen on it
+    $ JOB=$(docker run -d -p 4444 ubuntu:12.10 /bin/nc -l 4444)
+
+    # Which public port is NATed to my container?
+    $ PORT=$(docker port $JOB 4444 | awk -F: '{ print $2 }')
+
+    # Connect to the public port
+    $ echo hello world | nc 127.0.0.1 $PORT
+
+    # Verify that the network connection worked
+    $ echo "Daemon received: $(docker logs $JOB)"
+
+## Committing (saving) a container state
+
+Save your containers state to an image, so the state can be
+re-used.
+
+When you commit your container, Docker only stores the diff (difference) between
+the source image and the current state of the container's image. To list images
+you already have, use the `docker images` command.
+
+    # Commit your container to a new named image
+    $ docker commit <container> <some_name>
+
+    # List your images
+    $ docker images
+
+You now have an image state from which you can create new instances.
+
+## Where to go next
+
+* Work your way through the [Docker User Guide](userguide/index.md)
+* Read more about [*Share Images via Repositories*](userguide/containers/dockerrepos.md)
+* Review [*Command Line*](reference/commandline/cli.md)