diff --git a/README.md b/README.md index 49a418bae9..103410e799 100644 --- a/README.md +++ b/README.md @@ -84,8 +84,68 @@ Right now, the officially supported distributions are: Docker probably works on other distributions featuring a recent kernel, the AUFS patch, and up-to-date lxc. However this has not been tested. +Usage examples +============== + +Running an interactive shell +---------------------------- + +```bash + # Download a base image + docker import base + + # Run an interactive shell in the base image, + # allocate a tty, attach stdin and stdout + docker run -a -i -t base /bin/bash +``` + + +Starting a long-running worker process +-------------------------------------- + +```bash + # Run docker in daemon mode + (docker -d || echo "Docker daemon already running") & + + # Start a very useful long-running process + JOB=$(docker run /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 all running containers +------------------------------ + +```bash + docker ps +``` + + +Expose a service on a TCP port +------------------------------ + +```bash + # Expose port 4444 of this container, and tell netcat to listen on it + JOB=$(docker run -p 4444 base /bin/nc -l -p 4444) + + # Which public port is NATed to my container? + PORT=$(docker port $JOB 4444) + + # Connect to the public port via the host's public address + echo hello world | nc $(hostname) $PORT + + # Verify that the network connection worked + echo "Daemon received: $(docker logs $JOB)" +``` + + What is a Standard Container? ------------------------------ +============================= Docker defines a unit of software delivery called a Standard Container. The goal of a Standard Container is to encapsulate a software component and all its dependencies in a format that is self-describing and portable, so that any compliant runtime can run it without extra dependency, regardless of the underlying machine and the contents of the container.