Docker Primer

Primer for getting started with Docker. Primer is written primarily for linux/mac, and provides some of the most common commands required to get your Docker set-up going.

To contribute, click here.

Features

• Docker basics
• Most common commands
• Examples
• Links to videos
• Links to blog posts

Table of Contents

• What is Docker?
• Why use Docker?
• Docker Architecture
• Installation requirements
• Installation
• Using Docker
• Most common Docker commands
• Container commands
• Image commands
• Network commands
• Volumes commands
• Registry commands
• Dockerfile
• Layers
• Links
• Exposing Ports
• Security
• Best Practices
• Docker-Compose

What is Docker?

Docker is an open platform for developing, shipping, and running applications.

Why use Docker?

Docker allows developers to work in standardized environments using containers. What this essentially means is that "“Dockerized” apps are completely portable and can run anywhere, on any system, without the need to configure and set-up your enviroment.

Docker Architecture

Docker uses a client-server architecture. The Docker client (aka. Docker CLI) talks to the Docker daemon, which does the heavy lifting of building, running, and distributing your Docker containers.

Docker client

The Docker client (docker) is the primary way to interact with Docker. When you use commands such as docker run, the client sends these commands to the docker daemon (dockerd), which carries them out.

Docker daemon

The Docker daemon (dockerd) listens for Docker API requests and manages Docker objects such as images, containers, networks, and volumes. A daemon can also communicate with other daemons to manage Docker services.

Docker registry

A Docker registry stores Docker images. Docker Hub is a public registry that anyone can use, and Docker is configured to look for images on Docker Hub by default. You can even run your own private registry.

Instalation requirements

Linux

The 3.10.x kernel is the minimum requirement for Docker.

MacOS

10.8 “Mountain Lion” or newer is required.

Windows 10

Hyper-V must be enabled in BIOS

VT-D must also be enabled if available (Intel Processors).

Installation

If you are a complete Docker newbie, you should probably follow the tutorial for your operating system.

Linux

Run this quick and easy install script provided by Docker:

$ curl -sSL https://get.docker.com/ | sh

If you don't want to run a random shell script, please see the installation instructions for your distribution.

macOS

If you have Homebrew-Cask, type in your terminal:

$ brew cask install docker

Alternativley, you can download and install Docker Community Edition.

Once you've installed Docker Community Edition, click the docker icon in Launchpad. Then start up a container by typing:

$ docker run hello-world

That's it, you now have a running Docker container.

Windows 10

Official instructions to install Docker Desktop for Windows can be found here.

If you're using windows, please check out a more detailed explanation I've written for you here.

Once installed, open powershell as administrator and run:

# Display the version of docker installed:
$ docker version

# Pull, create, and run 'hello-world' container:
$ docker run hello-world

That's it, you now have a running Docker container.

Using Docker

Check Version

It is very important that you always know the current version of Docker you are currently running on at any point in time.

• docker version shows which version of docker you have running.

Get detailed information about your version (client and server) by running:

$ docker version
# Output will be detailed information about your docker version

Get only the version:

$ docker version --format '{{.Server.Version}}'
# 1.8.0

Most common Docker commands

These are some of the most common commands while using Docker. All of them link to Docker documentation page where you can see examples of usage.

I have also made a folder with all of my saved commands and examples. Check it out here.

Container commands

A Container is a runnable instance of an image. And an image is a read-only template with instructions for creating a Docker container.

To see some of my own container related examples and saved commands, go here.

Lifecycle

• docker create creates a container but does not start it.
• docker rename allows the container to be renamed.
• docker run creates and starts a container in one operation.
• docker rm deletes a container.
• docker update updates a container's resource limits.

Starting and Stopping

• docker start starts a container so it is running.
• docker stop gracefully stops a running container.
• docker restart stops and starts a container.
• docker pause pauses a running container, "freezing" it in place.
• docker unpause will unpause a running container.
• docker wait blocks until running container stops.
• docker kill sends a SIGKILL to a running container.
• docker attach will connect to a running container.

Info

• docker ps shows running containers.
• docker logs gets logs from container.
• docker inspect looks at all the info on a container (including IP address).
• docker events gets events from container.
• docker port shows public facing port of container.
• docker top shows running processes in container.
• docker stats shows containers' resource usage statistics.
• docker diff shows changed files in the container's FS.

Import / Export

• docker cp copies files or folders between a container and the local filesystem.
• docker export turns container filesystem into tarball archive stream to STDOUT.

Executing Commands

• docker exec to execute a command inside the container.

Data management

• docker system df shows Docker disk usage (for all Docker objects)
• docker system prune will delete ALL unused data (images, containers, networks, volumes)
• docker volume prune will delete all unused volumes
• docker network prune will delete all unused networks
• docker container prune will delete all unused containers
• docker image prune will delete all unused images

Image commands

Images are just templates for docker containers.

To see some of my own image related examples and saved commands, go here.

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, pausing it temporarily if it is running.
• docker rmi removes an image.
• 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).

Network commands

Docker has a networks feature that automatically creates 3 network interfaces when you create a container (bridge, host, none).

To read a bit more about it and see some of my own examples and saved commands, go here.

Lifecycle

• docker network create Create a new network (default type: bridge).
• docker network rm Remove one or more networks by name or identifier. No containers can be connected to the network when deleting it.

Info

• docker network ls List networks
• docker network inspect Display detailed information on one or more networks.

Connection

• docker network connect Connect a container to a network
• docker network disconnect Disconnect a container from a network

Volumes commands

Docker volumes are are files and folders that can be attached to containers (or perserved from within the container).

To read a bit more about it and see some of my own volumes related examples and saved commands, go here.

Lifecycle

• docker volume create
• docker volume rm

Info

• docker volume ls
• docker volume inspect

Registry commands

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.com hosts its own index to a central registry which contains a large number of repositories. Having said that, the central docker registry does not do a good job of verifying images and should be avoided if you're worried about security.

• docker login to login to a registry.
• docker logout to logout from 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.

Dockerfile

The configuration file. Sets up a Docker container when you run docker build on it. Vastly preferable to docker commit.

Dockerfile commands

• .dockerignore defines which files and folders should be avoided while building a docker image.
• FROM sets the Base Image for subsequent instructions.
• RUN execute any commands in a new layer on top of the current image and commit the results.
• CMD provide defaults for an executing container.
• EXPOSE informs Docker that the container listens on the specified network ports at runtime. NOTE: does not actually make ports accessible.
• ENV sets environment variable.
• ADD copies new files, directories or remote file to container. Invalidates caches. Avoid ADD and use COPY instead.
• COPY copies new files or directories to container. By default this copies as root regardless of the USER/WORKDIR settings. Use --chown=<user>:<group> to give ownership to another user/group. (Same for ADD.)
• ENTRYPOINT configures a container that will run as an executable.
• VOLUME creates a mount point for externally mounted volumes or other containers.
• USER sets the user name for following RUN / CMD / ENTRYPOINT commands.
• WORKDIR sets the working directory.
• ARG defines a build-time variable.
• ONBUILD adds a trigger instruction when the image is used as the base for another build.
• STOPSIGNAL sets the system call signal that will be sent to the container to exit.
• LABEL apply key/value metadata to your images, containers, or daemons.
• SHELL override default shell is used by docker to run commands.
• HEALTHCHECK tells docker how to test a container to check that it is still working.

Tutorial

• Flux7's Dockerfile Tutorial

Examples

• Examples
• Best practices for writing Dockerfiles
• Michael Crosby has some more Dockerfiles best practices / take 2.
• Building Good Docker Images / Building Better Docker Images
• Managing Container Configuration with Metadata
• How to write excellent Dockerfiles

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.

To read a bit more about it and see some of my own links related examples and saved commands, go here.

Exposing ports

Exposing incoming ports through the host container is fiddly but doable.

To read a bit more about it and see some of my own examples and saved commands, go here.

Security

The Docker security page goes into much more detail.

To read a bit more about it and see some of my own (shorter) explanations, go here.

Security Videos

• Using Docker Safely
• Securing your applications using Docker
• Container security: Do containers actually contain?
• Linux Containers: Future or Fantasy?

Best Practices

This is where general Docker best practices and war stories go:

• The Rabbit Hole of Using Docker in Automated Tests
• Bridget Kromhout has a useful blog post on running Docker in production at Dramafever.
• There's also a best practices blog post from Lyst.
• Building a Development Environment With Docker
• Discourse in a Docker Container

Docker-Compose

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. To learn more about all the features of Compose, see the list of features.

To see some of my own docker-compose examples and saved commands, go here.

To see one of my example docker-compose.yml files, go here.

License

MIT License

Inspiration for this primer

Many thanks to Will Sargent for making his docker cheet sheet. This primer is greatly inspired by his hard work. Please check out his repo and drop a star ;)