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.
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.
