How to use docker compose up command to manage containers

Introduction

In this lab, you will learn how to effectively manage containers using the docker compose up command. We will cover the fundamental usage of docker compose up to start services defined in a docker-compose.yml file, including running services in the foreground and detached mode.

Furthermore, you will explore advanced options of docker compose up, such as forcing container recreation with force-recreate, preventing unnecessary recreation with no-recreate, and automatically building images before starting containers. By the end of this lab, you will be proficient in using docker compose up for various container management scenarios.

Start services with docker compose up

In this step, you will learn how to start services defined in a docker-compose.yml file using the docker compose up command. Before we start, we need to install Docker Compose as it is not pre-installed in this environment.

First, let's install Docker Compose. We will download the latest stable version and make it executable.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Now that Docker Compose is installed, let's create a simple docker-compose.yml file to define a service. We will create a file named docker-compose.yml in your ~/project directory.

nano ~/project/docker-compose.yml

Add the following content to the file:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"

This docker-compose.yml file defines a single service named web. It uses the nginx:latest image and maps port 80 on the host to port 80 in the container.

Now, let's use docker compose up to start the service. Navigate to the ~/project directory and run the command.

cd ~/project
docker compose up

You will see output indicating that Docker Compose is creating and starting the web container. By default, docker compose up runs in the foreground, showing the logs of the running services.

To verify that the Nginx container is running, you can open a new terminal or use curl to access the web server.

curl http://localhost

You should see the default Nginx welcome page HTML output. This confirms that the web service is running and accessible.

To stop the services, press Ctrl+C in the terminal where docker compose up is running. This will stop and remove the containers.

Run services in detached mode

In the previous step, you started the services using docker compose up, which ran in the foreground. This is useful for debugging, but for running services in production or in the background, you'll want to use detached mode.

Detached mode means that Docker Compose will start the containers and then exit, leaving the containers running in the background. This allows you to continue using your terminal for other tasks.

To run the services in detached mode, you simply add the -d flag to the docker compose up command. Make sure you are in the ~/project directory where your docker-compose.yml file is located.

cd ~/project
docker compose up -d

You will see output indicating that the containers are being created and started, but the command will return you to the terminal prompt once the services are running.

To verify that the container is running in the background, you can use the docker ps command to list the running containers.

docker ps

You should see an entry for the project-web-1 container (the name is typically [directory_name]-[service_name]-[instance_number]).

You can still access the Nginx web server using curl to confirm it's working.

curl http://localhost

You should again see the default Nginx welcome page HTML output.

To stop the services that were started in detached mode, you can use the docker compose down command in the same directory as your docker-compose.yml file.

docker compose down

This command will stop and remove the containers, networks, and volumes created by docker compose up.

Recreate containers with force-recreate

In the previous step, you learned how to run services in detached mode. By default, when you run docker compose up again with the same docker-compose.yml file and the containers are already running, Docker Compose will not recreate the containers unless there are changes to the service definition (like the image or ports).

Sometimes, you might want to force Docker Compose to stop and recreate the containers even if there are no changes to the service definition. This can be useful for applying updates that don't involve changing the docker-compose.yml file, or simply to ensure a fresh start for the container.

To force the recreation of containers, you can use the --force-recreate flag with the docker compose up command.

First, ensure your web service is running in detached mode from the previous step. If not, run:

cd ~/project
docker compose up -d

Now, let's run docker compose up again with the --force-recreate flag.

cd ~/project
docker compose up -d --force-recreate

You will see output indicating that Docker Compose is stopping and then recreating the web container. Even though the docker-compose.yml file hasn't changed, the --force-recreate flag tells Docker Compose to tear down the existing container and build a new one based on the current configuration.

You can verify that the container was recreated by checking the container ID using docker ps. The container ID should be different from the one you saw before running the command with --force-recreate.

docker ps

Note the container ID in the output.

To clean up, stop the running services:

cd ~/project
docker compose down

Prevent recreation with no-recreate

In the previous step, you learned how to force the recreation of containers using the --force-recreate flag. Now, let's look at the opposite scenario: preventing recreation.

As mentioned before, by default, docker compose up will not recreate containers if they are already running and their configuration in the docker-compose.yml file hasn't changed. However, there might be situations where you want to explicitly ensure that existing containers are not recreated, even if there were minor changes that might otherwise trigger a recreation.

To prevent the recreation of containers, you can use the --no-recreate flag with the docker compose up command.

First, ensure your web service is stopped. If it's running, stop it using:

cd ~/project
docker compose down

Now, let's start the service using docker compose up -d.

cd ~/project
docker compose up -d

Verify that the container is running:

docker ps

Note the container ID.

Now, let's run docker compose up again with the --no-recreate flag.

cd ~/project
docker compose up -d --no-recreate

You will see output indicating that the service is up-to-date and the container is not being recreated. If you check docker ps again, you will see that the container ID is the same as before.

docker ps

This demonstrates that the --no-recreate flag successfully prevented Docker Compose from recreating the existing container.

To clean up, stop the running services:

cd ~/project
docker compose down

Build images before starting containers

In the previous steps, we used pre-built Docker images from Docker Hub (like nginx:latest). However, you will often need to build your own custom Docker images for your applications.

Docker Compose can automatically build images defined in your docker-compose.yml file before starting the services. This is typically done by specifying a build context instead of an image name for a service.

Let's modify our docker-compose.yml file to build a simple custom Nginx image.

First, create a new directory named nginx_custom inside ~/project.

cd ~/project
mkdir nginx_custom

Now, create a Dockerfile inside the nginx_custom directory.

nano ~/project/nginx_custom/Dockerfile

Add the following content to the Dockerfile:

FROM nginx:latest
RUN echo '<h1>Hello from Custom Nginx!</h1>' >/usr/share/nginx/html/index.html

This Dockerfile starts from the official nginx:latest image and then replaces the default index.html file with a custom one.

Next, modify your ~/project/docker-compose.yml file to use this Dockerfile for building the web service image. Open the file for editing:

nano ~/project/docker-compose.yml

Change the web service definition to use build instead of image:

version: "3.8"
services:
  web:
    build: ./nginx_custom
    ports:
      - "80:80"

Now, when you run docker compose up, Docker Compose will first build the image defined by the Dockerfile in the ./nginx_custom directory and then start a container using that newly built image.

Make sure you are in the ~/project directory and run:

cd ~/project
docker compose up -d

You will see output indicating that Docker Compose is building the image and then creating and starting the container.

To verify that the custom Nginx page is being served, use curl:

curl http://localhost

You should see the output <h1>Hello from Custom Nginx!</h1>, confirming that the image was built and the container is running with the custom content.

To clean up, stop the running services:

cd ~/project
docker compose down

Summary

In this lab, you learned how to use the docker compose up command to manage containers. You started by installing Docker Compose and creating a simple docker-compose.yml file to define a web service using the Nginx image. You then used docker compose up to start the service, observing that it runs in the foreground by default and displays container logs. You verified the running service by accessing the Nginx welcome page.

The lab also introduced running services in detached mode using the -d flag, allowing the command to exit while containers continue running in the background. You learned how to force the recreation of containers even if their configuration hasn't changed using the --force-recreate flag and how to prevent recreation of existing containers with the --no-recreate flag. Finally, you explored the --build flag to build or rebuild images before starting containers, ensuring that the latest image is used.