2015-06-08 03:07:20 +00:00
<!-- [metadata]>
+++
title = "Get started with containers"
description = "Common usage and commands"
keywords = ["Examples, Usage, basic commands, docker, documentation, examples"]
[menu.main]
parent = "smn_containers"
+++
<![end-metadata]-->
2014-04-16 00:53:12 +00:00
2015-06-08 03:07:20 +00:00
# "Get started with containers
2014-04-16 00:53:12 +00:00
2015-06-01 11:18:13 +00:00
This guide assumes you have a working installation of Docker. To verify Docker is
installed, use the following command:
2014-04-16 00:53:12 +00:00
# Check that you have a working install
2015-03-26 18:12:37 +00:00
$ docker info
2014-04-16 00:53:12 +00:00
2014-05-14 17:22:49 +00:00
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
2015-03-26 18:12:37 +00:00
Docker on your machine. Please
Additionally, depending on your Docker system configuration, you may be required
to preface each `docker` command with `sudo` . To avoid having to use `sudo` with
the `docker` command, your system administrator can create a Unix group called
`docker` and add users to it.
For more information about installing Docker or `sudo` configuration, refer to
the [installation ](/installation ) instructions for your operating system.
2014-04-16 00:53:12 +00:00
## Download a pre-built image
# Download an ubuntu image
2015-03-26 18:12:37 +00:00
$ docker pull ubuntu
2014-04-16 00:53:12 +00:00
2014-04-26 12:00:01 +00:00
This will find the `ubuntu` image by name on
2014-12-16 04:25:37 +00:00
[*Docker Hub* ](/userguide/dockerrepos/#searching-for-images )
2014-06-01 20:48:04 +00:00
and download it from [Docker Hub ](https://hub.docker.com ) to a local
2014-05-14 17:22:49 +00:00
image cache.
2014-04-16 00:53:12 +00:00
2014-04-18 20:21:55 +00:00
> **Note**:
2015-06-01 11:18:13 +00:00
> When the image is successfully downloaded, you see a 12 character
2014-04-18 20:21:55 +00:00
> 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
2015-06-01 11:18:13 +00:00
> `docker inspect` or `docker images --no-trunc=true`.
2014-04-16 00:53:12 +00:00
2014-12-29 08:19:42 +00:00
{{ include "no-remote-sudo.md" }}
2014-04-16 00:53:12 +00:00
## Running an interactive shell
2015-06-01 11:18:13 +00:00
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.
2014-04-16 00:53:12 +00:00
## Bind Docker to another host/port or a Unix socket
2014-05-14 17:22:49 +00:00
> **Warning**:
2014-04-18 20:21:55 +00:00
> 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.
2014-04-16 00:53:12 +00:00
2014-05-14 17:22:49 +00:00
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
2014-06-03 19:44:20 +00:00
*root* user. You *could* set it to `0.0.0.0:2375` or a specific host IP
2014-05-14 17:22:49 +00:00
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.
2014-04-16 00:53:12 +00:00
2014-05-14 17:22:49 +00:00
Similarly, the Docker client can use `-H` to connect to a custom port.
2014-04-16 00:53:12 +00:00
2014-05-14 17:22:49 +00:00
`-H` accepts host and port assignment in the following format:
2015-06-01 11:18:13 +00:00
tcp://[host][:port] or unix://path
2014-04-16 00:53:12 +00:00
For example:
2014-06-03 19:44:20 +00:00
- `tcp://host:2375` -> TCP connection on
host:2375
2014-05-14 17:22:49 +00:00
- `unix://path/to/socket` -> Unix socket located
2014-04-16 00:53:12 +00:00
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:
2015-06-01 11:18:13 +00:00
host[:port] or :port
2014-05-14 17:22:49 +00:00
Run Docker in daemon mode:
2014-05-01 14:13:34 +00:00
$ sudo < path to > /docker -H 0.0.0.0:5555 -d &
2014-05-14 17:22:49 +00:00
Download an `ubuntu` image:
2015-03-26 18:12:37 +00:00
$ docker -H :5555 pull ubuntu
2014-04-16 00:53:12 +00:00
2014-05-14 17:22:49 +00:00
You can use multiple `-H` , for example, if you want to listen on both
TCP and a Unix socket
2014-04-16 00:53:12 +00:00
# Run docker in daemon mode
2014-06-03 19:44:20 +00:00
$ sudo < path to > /docker -H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock -d &
2014-04-16 00:53:12 +00:00
# Download an ubuntu image, use default Unix socket
2015-03-26 18:12:37 +00:00
$ docker pull ubuntu
2014-04-16 00:53:12 +00:00
# OR use the TCP port
2015-03-26 18:12:37 +00:00
$ docker -H tcp://127.0.0.1:2375 pull ubuntu
2014-04-16 00:53:12 +00:00
## Starting a long-running worker process
# Start a very useful long-running process
2015-03-26 18:12:37 +00:00
$ JOB=$(docker run -d ubuntu /bin/sh -c "while true; do echo Hello world; sleep 1; done")
2014-04-16 00:53:12 +00:00
# Collect the output of the job so far
2015-03-26 18:12:37 +00:00
$ docker logs $JOB
2014-04-16 00:53:12 +00:00
# Kill the job
2015-03-26 18:12:37 +00:00
$ docker kill $JOB
2014-04-16 00:53:12 +00:00
## Listing containers
2015-03-26 18:12:37 +00:00
$ docker ps # Lists only running containers
$ docker ps -a # Lists all containers
2014-04-16 00:53:12 +00:00
## Controlling containers
# Start a new container
2015-03-26 18:12:37 +00:00
$ JOB=$(docker run -d ubuntu /bin/sh -c "while true; do echo Hello world; sleep 1; done")
2014-04-16 00:53:12 +00:00
# Stop the container
2015-03-26 18:12:37 +00:00
$ docker stop $JOB
2014-04-16 00:53:12 +00:00
# Start the container
2015-03-26 18:12:37 +00:00
$ docker start $JOB
2014-04-16 00:53:12 +00:00
# Restart the container
2015-03-26 18:12:37 +00:00
$ docker restart $JOB
2014-04-16 00:53:12 +00:00
# SIGKILL a container
2015-03-26 18:12:37 +00:00
$ docker kill $JOB
2014-04-16 00:53:12 +00:00
# Remove a container
2015-03-26 18:12:37 +00:00
$ docker stop $JOB # Container must be stopped to remove it
$ docker rm $JOB
2014-04-16 00:53:12 +00:00
## Bind a service on a TCP port
# Bind port 4444 of this container, and tell netcat to listen on it
2015-03-26 18:12:37 +00:00
$ JOB=$(docker run -d -p 4444 ubuntu:12.10 /bin/nc -l 4444)
2014-04-16 00:53:12 +00:00
# Which public port is NATed to my container?
2015-03-26 18:12:37 +00:00
$ PORT=$(docker port $JOB 4444 | awk -F: '{ print $2 }')
2014-04-16 00:53:12 +00:00
# Connect to the public port
2014-05-01 14:13:34 +00:00
$ echo hello world | nc 127.0.0.1 $PORT
2014-04-16 00:53:12 +00:00
# Verify that the network connection worked
2015-03-26 18:12:37 +00:00
$ echo "Daemon received: $(docker logs $JOB)"
2014-04-16 00:53:12 +00:00
## Committing (saving) a container state
2014-05-08 13:11:17 +00:00
Save your containers state to an image, so the state can be
2014-04-16 00:53:12 +00:00
re-used.
2015-06-01 11:18:13 +00:00
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.
2014-04-16 00:53:12 +00:00
# Commit your container to a new named image
2015-06-01 11:18:13 +00:00
$ docker commit < container > < some_name >
2014-04-16 00:53:12 +00:00
2015-04-25 08:28:39 +00:00
# List your images
2015-03-26 18:12:37 +00:00
$ docker images
2014-04-16 00:53:12 +00:00
2014-05-08 13:11:17 +00:00
You now have an image state from which you can create new instances.
2014-04-16 00:53:12 +00:00
2014-05-21 21:05:19 +00:00
Read more about [*Share Images via
2014-12-16 04:25:37 +00:00
Repositories*](/userguide/dockerrepos) or
2014-05-21 21:05:19 +00:00
continue to the complete [*Command
2014-12-16 04:25:37 +00:00
Line*](/reference/commandline/cli)