Docker Tutorial

In case you are not familiar with Docker, this tutorial should help you with the most used commands on ExoMy. For a full explanation also check the official Docker reference.

Docker is a software that allows to run applications in separated containers, that contain all the needed dependencies. In this way it is possible to easily distribute software since the container is mainly independent of the host operating system.

We should start with the three main components of Docker:

Dockerfile

A Dockerfile is a plain text file, that can be seen as a recipe or blueprint for a Docker image. In the Dockerfile you define a base operating system (Ubuntu in the case of Exomy) and each step that should be executed to create the full image, for example installing software.

Docker Image

Docker images are read-only templates, that contain everything to run a Docker container. Images can be build from Dockerfiles locally, or can be downloaded from the community at Dockerhub.

Docker Container

A container is a runnable instance of an image. When started, it runs your application. There can be multiple containers based on the same image.

How to use it

Handling Images

The docker build command builds a Docker image from a Dockerfile that is located under the given path or at the given URL:

docker build [OPTIONS] PATH | URL

A common option used with this command is --tag, which allows to give the build image an appropriate name.

For ExoMy the build command looks like following, when it is executed from the home folder:

docker build -t exomy ExoMy_Software/docker

To check whether the build was successful you can use:

docker image ls

to list all images available on your system.

Since images can take up a lot of disk space it is a good habit to delete unused ones from time to time with:

docker image rm IMAGE_NAME

Handling Containers

The command docker run is used to create a container based on an image and starts it using a given command. The docker run command takes this form:

docker run [OPTIONS] IMAGE [COMMAND]

If [COMMAND] is not specified, the CMD or ENTRYPOINT instructions from the Dockerfile are used.

You can have multiple containers based on the same image, as long as the containers have different names.

A list of all [OPTIONS] can be found on the Docker documentation. Here the most common ones, used for the operation of ExoMy should be discussed:

Command	Description
--interactive, -it	Lets you access the containers terminal after its started.
--name CONTAINER_NAME	Assign a name to the container.
--privileged	Gives extended privileges to the container. Use with care!
--publish, -p HOST:CONTAINER	Publish a container’s port(s) to the host.
--restart	Set the restart policy to no, on-failure, unless-stopped or always.
--rm	Automatically remove the container when it exits.
--volume, -v HOST_DIR:CONTANER_DIR	Mount a directory from the host to a directory in the container, so files can be stored permanent.

The options should be thought over before running the container, since they can not be changed afterwards.

To list all the running containers you can use:

docker container ls

To attach to a container use:

docker attach [NAME/ID]

To also show all the stopped containers use:

docker container ls -a

If you did not assign a name to your container, Docker will assign a randomly created name.

If you have a stopped container and you want to start it and attach to it use:

docker container start -a [NAME/ID]

To attach to a container with a second independent terminal run:

docker exec -it [NAME/ID] bash

Also containers can take up a lot of memory, so check an remove unused containers with:

docker container [NAME/ID]