Quickstart containers

This quickstart assumes you have a working installation of Docker. To verify Docker 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 anincomplete Docker installation or insufficient privileges to accessDocker on your machine. With the default installation of Docker dockercommands need to be run by a user that is in the docker group or by theroot user.

Depending on your Docker system configuration, you may be requiredto preface eachdocker command with sudo. One way to avoid having to usesudo with thedocker commands is to create a Unix group called docker andadd users that will be enteringdocker commands to the ‘docker’ group.

For more information about installing Docker or sudo configuration, refer totheinstallation 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 onDocker Huband download it fromDocker Hub to a localimage cache.

Note:When the image is successfully downloaded, you see a 12 characterhash539c0211cd76: Download complete which is theshort form of the image ID. These short image IDs are the first 12characters of the full image ID - which can be found usingdocker inspect ordocker 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 apseudo-TTY that attachesstdin and stdout.

To detach the tty without exiting the shell, use the escape sequenceCtrl-p +Ctrl-q. The container will continue to exist in a stopped stateonce exited. To list all containers, stopped and running, use thedocker ps -acommand.

Bind Docker to another host/port or a Unix socket

Warning:Changing the default docker daemon binding to aTCP port or Unixdocker user group will increase your security risksby allowing non-root users to gainroot access on the host. Make sureyou control access to docker. If you are bindingto 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 aspecific IP and port. By default, it will listen onunix:///var/run/docker.sock to allow only local connections by theroot user. Youcould set it to 0.0.0.0:2375 or a specific host IPto give access to everybody, but that isnot recommended becausethen it is trivial for someone to gain root access to the host where thedaemon is running.

Similarly, the Docker client can use -H to connect to a custom port.The Docker client will default to connecting tounix:///var/run/docker.sockon 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 port2376 when TLS encryptionis on, or port 2375 when communication is in plain text.
• tcp://host:2375 -> TCP connection onhost:2375
• tcp://host:2375/path -> TCP connection onhost:2375 and prepend path to all requests
• unix://path/to/socket -> Unix socket locatedat path/to/socket

-H, when empty, will default to the same value aswhen 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 bothTCP 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 bere-used.

When you commit your container, Docker only stores the diff (difference) betweenthe source image and the current state of the container’s image. To list imagesyou already have, use thedocker 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
• Read more about Share Images via Repositories
• Review Command Line