Docker

This page is about the virtualization software Docker.

References

Website: https://www.docker.com/
Wikipedia
Dockerfile reference: https://docs.docker.com/engine/reference/builder/

Glossary

Container: A Docker container is a running Docker image. When you create a container, it adds a writable layer on top of the layers of the immutable image.
Dockerfile: A script of instructions that define how to build a specific Docker image. A Docker image is created by running a Dockerfile.
Docker Hub: A public repository of free Docker images.
Image: A Docker image - sometimes also called a snapshot - is an immutable file that contains the source code, libraries, dependencies, tools, and other files needed for an application to run. A Docker image can consist of a series of layers. A layer is based upon its predecessor and records the difference to that predecessor.
Instance: xxx
Volume: xxx

Docker Server/Client

Summary

Docker is split into a server and a client that sends commands to the server to execute. The Docker server can run on the same machine as the client or in a virtual machine, that also can be local, remote or in the cloud.

Client basics

The client is a command line utility

docker

The utility has many commands/subcommands and options. To get help for a specific command such as in this example the "ps" command:

docker help ps

Usually you run the command line utility with sudo, because the command line utility communicates with the Docker server via pipe in the filesystem, and that pipe requires special privileges. As a convenience alternative to sudo you can add your system user to the docker system group - the pipe file is owned by that group, so after adding yourself to the group you will have the necessary privileges by yourself.

Build context

When you build a Docker image the Docker client sends the so-called "build context" to the Docker server. The build context are the files that you want to create the Docker image from. The Docker client packs all build context files into a tar archive and uploads this archive to the Docker server.

When you issue the command to build a Docker image you specify the build context as the last parameter. Typically this is the current working directory, e.g.

docker image build --tag <image-name> .

The .dockerignore file

By default the client will take all files (and folders) in the directory you specify as build context in the image building command. This can be problematic if the directory contains sensitive information, or if it contains files that make the Docker image larger than it would be actually necessary.

If a .dockerignore file exists in the build context folder it will specify which files and/or folders to exclude from the build context. This is a sample to show the most important use cases:

# Ignore the node_modules directory
node_modules/

# Ignore the secret.txt file
secret.txt

# Ignore git and cache folders
.git

# Ignoring all markdown and class files
*.md
**/*.class

Docker images

Dockerfile

TODO Write some basics about Dockerfiles

Layers

The following Dockerfile instructions create a layer: RUN, COPY, ADD. The other instructions will create intermediate layers and do not influence the size of your image.

List images

List all images

docker image ls

Create image

Command to create a Docker image from a Dockerfile that is located in the current working directory. The --tag option, although not required, is useful to give the image a human-readable name.

docker image build --tag <image-name> .

Because this is such a common action there is a shortcut:

docker build --tag <image-name> .

Get image from a repository

This command downloads an image from a repository such as Docker Hub:

docker image pull <image-name>

Shortcut:

docker pull <image-name>

Delete image

This command deletes an image

docker image rm

Docker containers

List containers

List all running containers

docker ps

List all containers (both running and not running)

docker ps --all

Create container

This command creates a container layer on top of the layers that form an image, but does not run the container:

docker create <image-name>

Run/start a container

This command runs a container that has previously been created:

docker start <container-name>

This command creates a container from an image and immediately runs it:

docker run <image-name>

The --rm argument immediately removes a container after it was run:

docker run --rm <image-name>

This command gives the container the name "foo"

docker run --name foo <image-name>

The following command runs the Docker process interactively:

docker run -it --name foo <image-name>

The -it option is actually two options:

The -i option is a boolean option that makes sure that the Docker process runs interactively (it opens STDIN).
The -t option is a boolean option that makes sure that Docker allocates a pseudo TTY and attaches it to the container's STDIN.

And this command runs the container in detached mode in the background:

docker run -d <image-name>

Mapping things from the host to the container:

# Maps a port from the host to another port in the container
docker run -d -p 80:80 <image-name>

# Maps a folder from the host into the docker image (aka "mounting a volume" in Docker lingo).
# Multiple -v options can be specified.
docker run -v "/foo:/bar" <image-name>

Normally when you start a Docker container it executes the command that was defined when the Docker image was created. You can override this by specifying a command on the command line. The following example runs bash instead of the default command:

docker run <image-name> /bin/bash

Stop a container

This command stops a container that is currently running, but does not remove it:

docker stop <container-name>

Remove a container

This command removes a container

docker container rm <container-name>

Show the logs of a container

This command shows the logs of a container, or its most recent run. This can be useful, for instance, to diagnose why a container terminated prematurely:

docker container logs <container-name>

Inspect the run parameters of a container

This command displays the run parameters of a container. This can be useful, for instance, to see how exactly a container was started up by

docker-compose

.

docker container inspect <container-name>

Executing commands in a running container

This command starts a bash command line shell in a running container:

sudo docker exec -it <container-name> /bin/bash

Copying files to/from a container

The docker cp command has about the same semantics as, for instance, scp:

sudo docker cp /path/to/host-file <container-name>:/path/to/container-folder
sudo docker cp <container-name>:/path/to/container-file /path/to/host-folder

Managing the Docker system

Export/import an image

Export a Docker image with this command. The target file is a TAR archive.

docker save -o <image-name>.tar <image-name>

An exported image can be transferred to another system and there imported by loading the TAR archive file:

docker load -i <image-name>.tar

It makes sense to tag the Docker image before exporting it, when it is then imported on the target system the tag will be preserved.

Remove unused data

This command removes unused data, i.e. stopped containers, dangling images,

docker system prune

Remove dangling images

Dangling images are images that have been superseded by a newer build of the same image. These can be listed like this:

docker image ls -f dangling=true

Remove dangling images:

docker system prune --filter=dangling=true

Multi-container applications (docker compose)

Basic syntax:

docker-compose -f docker-compose-foo.yml up -d

Discussion:

docker-compose can also be written as docker compose (i.e. without a dash)
-f = Use a non-default "compose" file. The default "compose" file is docker-compose.yml.
up = Create containers and start them.
-d = Run containers in the background (d = detached).