How to use docker compose ls command to list Compose projects

Introduction

In this lab, you will learn how to effectively use the docker compose ls command to list and manage your Docker Compose projects. We will begin by setting up a sample Compose project, including installing Docker Compose if necessary, creating a docker-compose.yml file, and starting the project.

Following the project setup, you will explore various ways to list your Compose projects using docker compose ls. This includes listing only running projects, listing all projects (including stopped ones), displaying only project names, and filtering projects based on specific criteria. By the end of this lab, you will be proficient in using docker compose ls to gain visibility into your Compose environments.

Skills Graph

Start a sample Compose project

In this step, we will learn how to start a sample Compose project. Before we can use Docker Compose, we need to install it. Since the LabEx VM environment does not have Docker Compose pre-installed, we will install it first.

We will download the Docker Compose binary 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

After the installation, we can verify the installation by checking the version of Docker Compose.

docker-compose --version

You should see the version information printed to the console, confirming that Docker Compose is installed correctly.

Now, let's create a simple Compose project. We will create a directory for our project and then create a docker-compose.yml file inside it. This file will define the services for our application.

First, create a directory named my-compose-app.

mkdir ~/project/my-compose-app
cd ~/project/my-compose-app

Next, create a file named docker-compose.yml in the ~/project/my-compose-app directory using the nano editor.

nano docker-compose.yml

Add the following content to the docker-compose.yml file. This file defines a single service named web that uses the nginx image.

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

Save the file and exit the nano editor (Press Ctrl + X, then Y, then Enter).

Before starting the service, we need to make sure the nginx:latest image is available locally. We can pull the image using the docker pull command.

docker pull nginx:latest

Now that we have the docker-compose.yml file and the necessary image, we can start the Compose project using the docker-compose up command. The -d flag runs the services in detached mode, meaning they will run in the background.

docker-compose up -d

This command will create and start the web service as defined in the docker-compose.yml file. You should see output indicating that the service is being created and started.

To verify that the service is running, you can use the docker ps command to list the running containers. You should see a container for the web service.

docker ps

You can also access the Nginx web server by opening a web browser and navigating to the IP address of your LabEx VM. Since we mapped port 80 of the container to port 80 of the host, you should see the default Nginx welcome page.

List running Compose projects using docker compose ls

In the previous step, we started a sample Compose project named my-compose-app. Now, we will learn how to list running Compose projects using the docker compose ls command.

The docker compose ls command is used to list all Compose projects. By default, it only shows running projects.

Make sure you are in the ~/project/my-compose-app directory where your docker-compose.yml file is located.

cd ~/project/my-compose-app

Now, execute the docker compose ls command.

docker compose ls

You should see output similar to this:

NAME              STATUS    CONFIG FILES
my-compose-app    running   docker-compose.yml

This output shows that there is one running Compose project named my-compose-app, and it is using the docker-compose.yml configuration file.

The docker compose ls command is a quick way to see which of your Compose projects are currently active and running containers.

List all Compose projects including stopped ones using docker compose ls -a

In the previous step, we listed the running Compose projects. By default, docker compose ls only shows projects that have at least one container running. To see all Compose projects, including those that are stopped, we need to use the -a flag.

First, let's stop the my-compose-app project we started in the first step. Make sure you are in the ~/project/my-compose-app directory.

cd ~/project/my-compose-app

Now, stop the project using the docker-compose down command. This command stops and removes the containers, networks, and volumes created by docker-compose up.

docker-compose down

You should see output indicating that the services and resources are being stopped and removed.

Now that the project is stopped, let's try listing the Compose projects again using the default docker compose ls command.

docker compose ls

This time, you should not see the my-compose-app project listed because it is stopped.

Now, let's use the docker compose ls -a command to list all Compose projects, including the stopped ones.

docker compose ls -a

You should now see output similar to this:

NAME              STATUS     CONFIG FILES
my-compose-app    exited     docker-compose.yml

This output shows that the my-compose-app project exists, even though its status is exited (stopped). The -a flag is useful for seeing all the Compose projects you have defined on your system, regardless of their current state.

List only project names using docker compose ls -q

In the previous steps, we listed Compose projects with their status and configuration files. Sometimes, you might only need a list of the project names, for example, to use in a script. The docker compose ls -q command allows you to do this.

The -q flag stands for "quiet" and it suppresses all output except for the project names.

Make sure you are in the ~/project/my-compose-app directory.

cd ~/project/my-compose-app

Now, execute the docker compose ls -q command.

docker compose ls -q

You should see only the name of the Compose project printed to the console:

my-compose-app

This is useful when you want to get a clean list of project names without any extra information. You can combine the -q flag with the -a flag to list the names of all Compose projects, including stopped ones.

Let's try that:

docker compose ls -a -q

You should still see:

my-compose-app

This confirms that the -q flag only outputs the project names, regardless of whether the project is running or stopped when combined with -a.

Filter Compose projects using docker compose ls --filter

In this final step, we will explore how to filter the output of docker compose ls using the --filter flag. This is useful when you have many Compose projects and want to find specific ones based on certain criteria.

The --filter flag allows you to specify key-value pairs to filter the results. A common filter is by status.

First, let's make sure our my-compose-app project is stopped. We stopped it in the previous step, but it's good practice to confirm.

cd ~/project/my-compose-app
docker-compose down

Now, let's use the --filter flag to list only running Compose projects. Since our project is stopped, this command should not show any results.

docker compose ls --filter status=running

You should see no output, as there are no running Compose projects.

Now, let's use the --filter flag to list only stopped Compose projects.

docker compose ls --filter status=exited

You should see output similar to this:

NAME              STATUS     CONFIG FILES
my-compose-app    exited     docker-compose.yml

This shows that the my-compose-app project is listed because its status is exited.

You can also filter by other criteria, such as the project name. Let's filter for the project named my-compose-app.

docker compose ls --filter name=my-compose-app

This should also show the my-compose-app project:

NAME              STATUS     CONFIG FILES
my-compose-app    exited     docker-compose.yml

The --filter flag provides a powerful way to manage and view your Compose projects, especially in environments with many different applications defined by Compose files.

Summary

In this lab, we learned how to use the docker compose ls command to list Docker Compose projects. We began by installing Docker Compose and then created and started a sample Compose project using a docker-compose.yml file and the docker-compose up -d command.

We then explored the different options of the docker compose ls command. We used docker compose ls to list running projects, docker compose ls -a to list all projects including stopped ones, docker compose ls -q to list only project names, and docker compose ls --filter to filter projects based on specific criteria. These steps demonstrated the versatility of the docker compose ls command for managing and inspecting Compose projects.