Dockerfile vs docker-compose: What's the difference?

Difference between docker-compose and Dockerfile

The key difference between the Dockerfile and docker-compose is that the Dockerfile describes how to build Docker images, while docker-compose is used to run Docker containers.

The contents of a Dockerfile describe how to create and build a Docker image, while docker-compose is a command that runs Docker containers based on settings described in a docker-compose.yaml file.

How the Dockerfile works

Let’s say you want to build a Docker image that hosts your website on the Nginx web server. To do this, you code a Dockerfile that instructs to use the official Nginx image from DockerHub. Then, add a line in your Dockerfile that copies all of your website files into the Nginx image’s web hosting directory.

For example, a Dockerfile that describes how to create a custom Nginx image that hosts your HTML files might look like this:

FROM nginx:latest
COPY ./hello-world.html /usr/share/nginx/html/

When the image is assembled, this Dockerfile tells the docker build command to start with the latest Nginx image, and then to copy your hello-world.html file into the file serving folder of Nginx.

Dockerfile image building

To create a new, custom image based on this example Dockerfile, run the docker build command:

$ docker build -t my-nginx-image:latest .

Note that the dot at the end tells the docker build command to look for the Dockerfile in the current directory. Leave this out and you’ll get the “docker build requires exactly 1 argument” error.

After this command runs, a query of the Docker images installed on your local computer includes an image named my-nginx-image in the listing:

$ docker images
REPOSITORY     TAG    IMAGE ID     CREATED     SIZE
my-nginx-image latest c58ef9bfbb57 7 days ago 144MB

The Dockerfile is like a recipe that describes the steps the docker build command must follow to cook up a new, custom Docker image.

This example Dockerfile builds a custom Apache HTTP server image that is pre-loaded with website files.

How docker-compose works

Unlike the Dockerfile, the docker-compose command and the docker-compose.yaml file the command depends upon are not used to actually build Docker images. Instead, docker-compose is used to describe how to run Docker images as containers.

In Docker, you build images while you run containers. From one Docker image, many instances of containers can be spawned.

— Cameron McKenzie (@cameronmcnz) May 19, 2022

The docker-compose.yaml file describes how to parameterize a Docker image when it runs as a container. The following is a list of information a docker-compose.yaml file might include about how to run a Docker container:

• how much memory to assign
• security configuration
• how many virtual CPUs to allocate
• network settings
• host to Docker container port mappings
• where to store temporary files
• restart policies
• whether to limit read and write rates

Example of a docker-compose.yaml file

For example, a docker-compose.yaml file that describes how to run the image created with the Dockerfile above might look like this:

version: '3.9'
services:
  my-nginx-service:
    container_name: my-website
    image: my-nginx-image:latest
    cpus: 1.5
    mem_limit: 2048m
    ports:
      - "8080:80"

As you can see, this docker-compose.yaml file describes a variety of runtime parameters for the custom Nginx Docker image to run as a container. The file describes how much memory to allocate, how many CPUs to use, how to map internal and external ports and even the name of the Docker image to use.

In this docker-compose.yaml file example, the image being used is named my-nginx-image, which we created with the Dockerfile above.

The docker-compose command and YAML file

The docker-compose.yaml file then gets used by the docker-compose up command.

The docker-compose up command creates a container parameterized according to the YAML file and then runs it. That command then uses the docker-compose.yaml file to run a container.

The following command, when run in the same folder as a docker-compose.yaml file listed above, creates and runs a new container based on the YAML file’s configuration settings:

dockerfile@comparison /c/compose/rock-paper-docker 
$ docker-compose up -d 
Creating network "rock-paper-docker_default" with the default driver
Pulling my-nginx-service (nginx:latest)...
latest: Pulling from library/nginxDigest: sha256:2d1f8839
Status: Downloaded newer image for nginx:latest
Creating my-website with docker-compose up ...
Creating my-website with docker-compose up... done

Dockerfile and docker-compose combined

Often when a container is run, especially in a development or testing environment, it’s best to use the most up-to-date image with the latest software deployed into it. In this case, the docker-compose command actually uses a Dockerfile to build the latest version of a Docker image before it runs it.

The docker-compose.yaml file can reference a Dockerfile and force a new Docker image to be built. However, the opposite is not true. A Dockerfile cannot invoke the docker-compose up command or reference a docker-compose.yaml file.

This docker-compose.yaml file for the Apache httpd web server describes how to map volumes, configure ports and name the Docker container when it runs.

List of docker-compose and Dockerfile differences

The three primary differences between the Dockerfile and docker-compose are:

1. The Dockerfile is used to build images while the docker-compose.yaml file is used to run images.
2. The Dockerfile uses the docker build command, while the docker-compose.yaml file uses the docker-compose up command.
3. A docker-compose.yaml file can reference a Dockerfile, but a Dockerfile can’t reference a docker-compose file.

Both the Dockerfile and docker-compose are important resources in the development and deployment of cloud-native applications. But knowing the difference between docker-compose and the Dockerfile is important. The Dockerfile is used to build images, while docker-compose helps you run them as containers.