In the spirit of the programmer confessions on Twitter last week:

Whenever I need to run Docker containers manually, I have to look up something about the basic syntax. And I do this for a living.

Now, that would be absolutely fine, except for a few things: the official Docker run reference is a mile long and horrible to navigate, the Mac OS X Docker distribution doesn’t come with man pages, and to top it off, docker run --help is mostly useless.

If you are not familiar with Docker run at all, it is used to run new Docker containers. This is the command syntax:

docker run [options] <image> [command]

Below are my most Googled Docker run options, aka. My Docker run cheatsheet.

Mount a volume from the host machine

-v <directory-on-host>:<directory-in-container>

Example: Run Jenkins, mounting the data directory to /data/container-jenkins on the host:

docker run -v /data/container-jenkins:/var/jenkins_home jenkins:latest

Pro tip: Run Jenkins that can build Docker images using the host’s Docker:

docker run -v /var/run/docker.sock:/var/run/docker.sock jenkins:latest

Publish a port on the host machine

-p <port-on-host>:<port-on-container>

Example: Run elasticsearch and publish the default HTTP port:

docker run -p 9200:9200 elasticsearch:latest

Pro tip: Publish all ports that are EXPOSE’d in the Dockerfile:

docker run -P elasticsearch:latest

And to see the ports that were automagically mapped on the host:

docker port <id-of-running-container>

Remember: Host comes first - both in volumes and ports.

Mount volumes from another container

--volumes-from <container-id>

Example: Create a data container, and use its volumes:

docker create -v /data --name data ubuntu
docker run -it --volumes-from data ubuntu bash

The directory /data now persists between docker run invocations.

Run a container interactively


Example: Run bash in ubuntu:

docker run -it ubuntu:latest bash

Remember: interactive tty

Run a container in the background (detached)


Example: Run a Jenkins server in the background, mapping port 8080 to the host:

docker run -d -p8080:8080 --name jenkins jenkins:latest

Pro tip: From the above container, get the Jenkins admin password needed for setup:

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Pass environment variables to a container

-e 'NAME=value'

Example: Run a MySQL container with a specified root password:

docker run -e 'MYSQL_ROOT_PASSWORD=test' mysql:latest

Pro tip: Pass a bunch of variables in a file:

cat > env.txt

docker run --env-file env.txt mysql:latest

Restart a container automatically

--restart <always|unless-stopped|on-failure|no>
  • always: restart always, including reboots of host
  • unless-stopped: as always, unless the container has been stopped with docker stop
  • on-failure: restart if the parent process in the container returns non-zero, not on reboots of host
  • no: never restart (default)

Example: Run nginx and restart it only if it fails:

docker run --restart on-failure nginx:latest

Pro tip: Run eclipse in a container, and keep it running through crashes and reboots:

docker run -it --rm \
           -e DISPLAY=$DISPLAY \
           -v /tmp/.X11-unix:/tmp/.X11-unix \
           -v `pwd`:/workspace \
           --restart always \

Run a container as a different user

-u <username>

Example: Run bash on Ubuntu as nobody:

docker run -it -u nobody ubuntu:latest bash

Specify a custom working directory

-w <directory-in-container>

Example: Mount the current directory as the working directory in a container:

docker run -it -v $(pwd):$(pwd) -w $(pwd) ubuntu:latest bash

Releaseworks Academy has a free online training course on Docker & Jenkins best practices: