Docker Cheat Sheet
NOTE: This used to be a gist that continually expanded. It's now a github project because it's considerably easier for other people to edit, fix and expand on Docker using Github. Just click README.md, and then on the "writing pen" icon on the right to edit.
- Why
- TL;DR I just want a dev environment
- Prerequisites
- Installation
- Containers
- Images
- Registry and Repository
- Dockerfile
- Layers
- Links
- Volumes
- Exposing Ports
- Best Practices
- Tips
- Tools
Why
"With Docker, developers can build any app in any language using any toolchain. “Dockerized” apps are completely portable and can run anywhere - colleagues’ OS X and Windows laptops, QA servers running Ubuntu in the cloud, and production data center VMs running Red Hat.
Developers can get going quickly by starting with one of the 13,000+ apps available on Docker Hub. Docker manages and tracks changes and dependencies, making it easier for sysadmins to understand how the apps that developers build work. And with Docker Hub, developers can automate their build pipeline and share artifacts with collaborators through public or private repositories.
Docker helps developers build and ship higher-quality applications, faster." -- What is Docker
TL;DR, I just want a dev environment
- A Docker Dev Environment in 24 Hours!
- Building a Development Environment With Docker
- Discourse in a Docker Container
You may also like to try the tools section.
Prerequisites
I use Oh My Zsh with the Docker plugin for autocompletion of docker commands. YMMV.
Linux
You should have at least a 3.8 kernel, but 3.10.x is recommended.
MacOS
Use Homebrew.
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"
Installation
installation Instrunctions are available. Docker has recognized that installation / deployment is a PITA, and Docker Machine aka bug 8681 deals with this specifically.
Linux
Quick and easy install script provided by Docker:
curl -sSL https://get.docker.com/ | sh
If you're not willing to run a random shell script, please see the installation instructions for your distribution.
Mac OS X
Download Docker for OSX from the Github Releases page.
The canonical way to use Docker is with the aid of the boot2docker VM. However, using the out of the box boot2docker doesn't give me control over my Vagrant instances (especially the lack of port forwarding). So here's how to use boot2docker from a Vagrant instance.
We use the YungSang modified boot2docker instance from the Vagrant Cloud:
mkdir ~/boot2docker
cd ~/boot2docker
vagrant init yungsang/boot2docker
vagrant up
export DOCKER_HOST=tcp://localhost:2375
docker version
NOTE: the YungSang boot2docker opens up port forwarding to the network, so is not safe on public wifi. You can make a good argument that docker without TLS is fundamentally unsafe. I only do it because I have Hands Off installed to limit external network access.
Then start up a container:
docker run -i -t ubuntu /bin/bash
That's it, you have a running Docker container.
Containers
Your basic isolated Docker process. Containers are to Virtual Machines as threads are to processes. Or you can think of them as chroots on steroids.
Lifecycle
docker create
creates a container but does not start it.docker run
creates and starts a container in one operation.docker stop
stops it.docker start
will start it again.docker restart
restarts a container.docker rm
deletes a container.docker kill
sends a SIGKILL to a container.docker attach
will connect to a running container.docker wait
blocks until container stops.
If you want to run and then interact with a container, docker start
, then spawn a shell as described in Executing Commands.
If you want a transient container, docker run --rm
will remove the container after it stops.
If you want to poke around in an image, docker run -t -i <myimage> <myshell>
to open a tty.
If you want to map a directory on the host to a docker container, docker run -v $HOSTDIR:$DOCKERDIR
. Also see Volumes.
If you want to integrate a container with a host process manager, start the daemon with -r=false
then use docker start -a
.
If you want to expose container ports through the host, see the exposing ports section.
Restart policies on crashed docker instances are covered here.
Info
docker ps
shows running containers.docker inspect
looks at all the info on a container (including IP address).docker logs
gets logs from container.docker events
gets events from container.docker port
shows public facing port of container.docker top
shows running processes in container.docker diff
shows changed files in the container's FS.
docker ps -a
shows running and stopped containers.
Import / Export
There doesn't seem to be a way to use docker directly to import files into a container's filesystem. The closest thing is to mount a host file or directory as a data volume and copy it from inside the container.
docker cp
copies files or folders out of a container's filesystem.docker export
turns container filesystem into tarball.
Executing Commands
docker exec
to execute a command in container.
To enter a running container, attach a new shell process to a running container called foo, use: docker exec -it foo /bin/bash
.
Images
Images are just templates for docker containers.
Lifecycle
docker images
shows all images.docker import
creates an image from a tarball.docker build
creates image from Dockerfile.docker commit
creates image from a container.docker rmi
removes an image.docker insert
inserts a file from URL into image. (kind of odd, you'd think images would be immutable after create)docker load
loads an image from a tar archive as STDIN, including images and tags (as of 0.7).docker save
saves an image to a tar archive stream to STDOUT with all parent layers, tags & versions (as of 0.7).
Info
docker history
shows history of image.docker tag
tags an image to a name (local or registry).
Docker image ids are sensitive information and should not be exposed to the outside world. Treat them like passwords.
Registry & Repository
A repository is a hosted collection of tagged images that together create the file system for a container.
A registry is a host -- a server that stores repositories and provides an HTTP API for managing the uploading and downloading of repositories.
Docker.io hosts its own index to a central registry which contains a large number of repositories.
docker login
to login to a registry.docker search
searches registry for image.docker pull
pulls an image from registry to local machine.docker push
pushes an image to the registry from local machine.
Run local registry
Registry implementation has an official image for basic setup that can be launched with
docker run -p 5000:5000 registry
Note that this installation does not have any authorization controls. You may use option -P -p 127.0.0.1:5000:5000
to limit connections to localhost only.
In order to push to this repository tag image with repositoryHostName:5000/imageName
then push this tag.
Dockerfile
The configuration file. Sets up a Docker container when you run docker build
on it. Vastly preferable to docker commit
.
Instructions
Tutorial
Examples
Best Practices
Docker documentation: Best practices for writing Dockerfiles
Best to look at http://github.com/wsargent/docker-devenv and the best practices / take 2 for more details.
Bridget Kromhout has a useful blog post on running Docker in production at Dramafever. There's also a best practices blog post from Lyst.
If you use jEdit, I've put up a syntax highlighting module for Dockerfile you can use.
Layers
The versioned filesystem in Docker is based on layers. They're like git commits or changesets for filesystems.
Links
Links are how Docker containers talk to each other through TCP/IP ports. Linking into Redis and Atlassian show worked examples. You can also (in 0.11) resolve links by hostname.
NOTE: If you want containers to ONLY communicate with each other through links, start the docker daemon with -icc=false
to disable inter process communication.
If you have a container with the name CONTAINER (specified by docker run --name CONTAINER
) and in the Dockerfile, it has an exposed port:
EXPOSE 1337
Then if we create another container called LINKED like so:
docker run -d --link CONTAINER:ALIAS --name LINKED user/wordpress
Then the exposed ports and aliases of CONTAINER will show up in LINKED with the following environment variables:
$ALIAS_PORT_1337_TCP_PORT
$ALIAS_PORT_1337_TCP_ADDR
And you can connect to it that way.
To delete links, use docker rm --link
.
Volumes
Docker volumes are free-floating filesystems. They don't have to be connected to a particular container.
Volumes are useful in situations where you can't use links (which are TCP/IP only). For instance, if you need to have two docker instances communicate by leaving stuff on the filesystem.
You can mount them in several docker containers at once, using docker run -volume-from
Because volumes are isolated filesystems, they are often used to store state from computations between transient containers. That is, you can have a stateless and transient container run from a recipe, blow it away, and then have a second instance of the transient container pick up from where the last one left off.
See advanced volumes for more details. Container42 is also helpful.
As of 1.3, you can map MacOS host directories as docker volumes through boot2docker:
docker run -v /Users/wsargent/myapp/src:/src
You can also use remote NFS volume if you're feeling brave.
Exposing ports
Exposing incoming ports through the host container is fiddly but doable.
The fastest way is to map the container port to the host port (only using localhost interface) using -p
:
docker run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage
If you don't want to use the -p
option on the command line, you can persist port forwarding by using EXPOSE:
EXPOSE <CONTAINERPORT>
If you're running Docker in Virtualbox, you then need to forward the port there as well, using forwarded_port. It can be useful to define something in Vagrantfile to expose a range of ports so that you can dynamically map them:
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
...
(49000..49900).each do |port|
config.vm.network :forwarded_port, :host => port, :guest => port
end
...
end
If you forget what you mapped the port to on the host container, use docker port
to show it:
docker port CONTAINER $CONTAINERPORT
Tips
Sources:
Last Ids
alias dl='docker ps -l -q'
docker run ubuntu echo hello world
docker commit `dl` helloworld
Commit with command (needs Dockerfile)
docker commit -run='{"Cmd":["postgres", "-too -many -opts"]}' `dl` postgres
Get IP address
docker inspect `dl` | grep IPAddress | cut -d '"' -f 4
or
wget http://stedolan.github.io/jq/download/source/jq-1.3.tar.gz
tar xzvf jq-1.3.tar.gz
cd jq-1.3
./configure && make && sudo make install
docker inspect `dl` | jq -r '.[0].NetworkSettings.IPAddress'
or (this is unverified)
docker inspect -f '{{ .NetworkSettings.IPAddress }}' <container_name>
Get port mapping
docker inspect -f '{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' <containername>
Find containers by regular expression
for i in $(docker ps -a | grep "REGEXP_PATTERN" | cut -f1 -d" "); do echo $i; done`
Get Environment Settings
docker run --rm ubuntu env
Kill running containers
docker kill $(docker ps -q)
Delete old containers
docker ps -a | grep 'weeks ago' | awk '{print $1}' | xargs docker rm
Delete stopped containers
docker rm `docker ps -a -q`
Delete dangling images
docker rmi $(docker images -q -f dangling=true)
Delete all images
docker rmi $(docker images -q)
Show image dependencies
docker images -viz | dot -Tpng -o docker.png
Tools
Fig
Fig is a helper app that makes it easier to run multiple docker containers on the same host. I would expect it to be used during dev/qa more than in production.
Fig works with a fig.yml
file (default name, use -f
to provide a different filename) that defines the containers you wish to use with it. Fig will take its project name from the name of the folder containing your yml configuration but you can override that with the -p
parameter.
Once I have my config defined, I can use fig up -d
to run it (the -d
runs it as a background task). This will build (if required) start and link any containers.
You can do everything you do with fig using docker directly but running multiple containers with parameters would require some sort of script if you plan to do it more than once so the yml config of fig and the convenience commands it provides are worth considering.
Here's an example of setting up a fig.yml
for an app with an apache packaged client container and a tomcat packaged app war:
First, here are the two docker commands to run these containers:
docker run -p 8080:8080 -v /Users/me/tomcatwork/trial.properties:/usr/share/tomcat6/trial.properties:rw -d me/tcfull
docker run -p 80:80 -v /Users/me/dockerwork/localproxy.conf:/etc/apache2/conf-enabled/proxy.conf:rw -d me/afull
at this point, I haven't linked the containers - I'm using the proxy.conf to specify the tomcat address. my fig.yml looks like this:
app:
image: me/tcfull
ports:
- "8080"
volumes:
- /Users/me/tomcatwork/trial.properties:/usr/share/tomcat6/trial.properties:rw
web:
image: me/afull
ports:
- "80:80"
volumes:
- /Users/me/figwork/proxy.conf:/etc/apache2/conf-enabled/proxy.conf:rw
links:
- app
As you can see it follows the docker commands with the addition of names for the containers and a links section for the web container, linking it to the app container.
As part of that linking process, docker will copy any environment variables defined in the app container over to the web container, define new environment variables for the address the app container is running at and also add an app entry in the etc/hosts file for the web container. I can modify my proxy conf to address http://app:8080
and fig/docker will take care of the rest.
I can then use commands like fig stop
and fig rm
to stop all my containers and remove them.
NB - docker will eventually absorb figs functionality with docker groups and docker up but it looks like they're keeping the yml config so it should be pretty seamless when it happens.
Troubleshooting
fig run
is a useful command for debugging issues. It allows me to startup a named container (and any it links to) and run a one off command.
This allows me to do things like fig run web env
which will give me a list of all the environment variables that are available on the web container including the ones generated via the link to app.
I can also use fig run web bash
to run my web container interactively the way it has been setup by fig with the link to app so I can debug any issues from the command line.
Panamax
Nice web UI, will let you set up and download multiple docker containers.