Resolving the 'docker-compose: command not found' Error

Introduction

This lab provides a practical guide to resolving the "docker-compose: command not found" error, a common issue that Docker users encounter. Docker Compose is an essential tool for managing multi-container Docker applications, and encountering this error can impede your workflow. By completing this lab, you will gain the skills to troubleshoot and fix this issue, allowing you to continue developing and deploying your containerized applications effectively.

This Lab requires an internet connection for learning, thus only Pro users can start the VM. Upgrade your account to Pro.

Skills Graph

Understanding Docker Compose and Verifying Installation

What is Docker Compose?

Docker Compose is a tool that helps you define and share multi-container applications. With Compose, you can create a YAML file to configure your application's services, then start all services with a single command. It simplifies the process of managing multiple containers that work together.

Checking If Docker Compose Is Installed

Let's first check if Docker Compose is already installed on your system. Open a terminal and run:

docker-compose --version

You'll see output similar to:

docker-compose: command not found

However, if you receive an error message like docker-compose: command not found, it means Docker Compose is not installed or not properly configured in your system's PATH.

Verifying Docker Installation

Before we install Docker Compose, let's verify that Docker itself is properly installed. Run:

docker --version

You should see output similar to:

Docker version 20.10.21, build 20.10.21-0ubuntu1~22.04.3

If you don't see this output, Docker may not be properly installed. However, for this lab, we'll focus on resolving the Docker Compose issue.

Installing Docker Compose

Since we confirmed that Docker Compose is not installed or not accessible, let's install it. There are a few different methods to install Docker Compose, but we'll focus on the most straightforward approach for Ubuntu systems.

Method 1: Using apt Package Manager

The simplest way to install Docker Compose is through the apt package manager. Let's do that:

1. First, Setup the repository and install the dependencies:

## Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

## Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

You should see output showing the update process.

2. Next, install Docker Compose:

sudo apt install -y docker-compose-plugin

You'll see output showing the installation progress.

3. After installation completes, verify it worked by checking the version:

docker compose version

Note: In newer Docker installations, the command is docker compose (with a space) rather than docker-compose (with a hyphen).

You should see output similar to:

Docker Compose version v2.33.1

Method 2: Using curl to Install a Specific Version

You can skip this method if you have already installed Docker Compose using the apt method.

If the apt method didn't work or you need a specific version, you can install Docker Compose directly:

1. Create a directory for Docker CLI plugins if it doesn't exist:

mkdir -p ~/.docker/cli-plugins/

2. Download the Docker Compose binary:

curl -SL https://github.com/docker/compose/releases/download/v2.16.0/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose

You'll see a progress bar as the file downloads.

3. Make the binary executable:

chmod +x ~/.docker/cli-plugins/docker-compose

4. Verify the installation:

docker compose version

You should see output showing the Docker Compose version.

Creating a Simple Docker Compose Project

Now that we've successfully installed Docker Compose, let's create a simple Docker Compose project to ensure everything is working correctly.

Creating a Project Directory

First, let's create a directory for our Docker Compose project:

mkdir -p ~/project/docker-compose-test
cd ~/project/docker-compose-test

Creating a Docker Compose File

Now, let's create a simple Docker Compose file that will run a basic Nginx web server. Create a file named docker-compose.yml using the nano text editor:

nano docker-compose.yml

In the editor, add the following content:

version: "3"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html

This configuration defines:

• A service named "web" using the latest Nginx image
• Port mapping from the container's port 80 to our host's port 8080
• A volume that maps a local directory to the Nginx web root

Press Ctrl+O then Enter to save the file, and Ctrl+X to exit nano.

Creating HTML Content

Let's create the html directory and a simple index.html file:

mkdir -p html
nano html/index.html

In the editor, add the following HTML content:

<!DOCTYPE html>
<html>
  <head>
    <title>Docker Compose Test</title>
  </head>
  <body>
    <h1>Docker Compose is working!</h1>
    <p>
      If you can see this page, you have successfully resolved the
      docker-compose issue.
    </p>
  </body>
</html>

Press Ctrl+O then Enter to save the file, and Ctrl+X to exit nano.

Running the Docker Compose Project

Now, let's run our Docker Compose project:

docker compose up -d

The -d flag runs the containers in detached mode (in the background).

You should see output similar to:

Creating network "docker-compose-test_default" with the default driver
Creating docker-compose-test_web_1 ... done

This indicates that Docker Compose has successfully created and started your container.

Verifying the Web Server

Let's verify that our web server is running correctly:

curl http://localhost:8080

You should see the HTML content you created earlier:

<!DOCTYPE html>
<html>
  <head>
    <title>Docker Compose Test</title>
  </head>
  <body>
    <h1>Docker Compose is working!</h1>
    <p>
      If you can see this page, you have successfully resolved the
      docker-compose issue.
    </p>
  </body>
</html>

This confirms that Docker Compose is working correctly.

Managing Docker Compose Applications

Now that we've successfully set up and run a Docker Compose application, let's learn how to manage it with various Docker Compose commands.

Checking Running Containers

To check the status of your Docker Compose containers, run:

cd ~/project/docker-compose-test
docker compose ps

You should see output similar to:

NAME                        COMMAND                  SERVICE             STATUS              PORTS
docker-compose-test-web-1   "/docker-entrypoint.…"   web                 running             0.0.0.0:8080->80/tcp

This shows that your Nginx web server container is running and the port mapping is active.

Viewing Container Logs

To view the logs from your containers, run:

docker compose logs

This will display the combined logs from all containers in your Docker Compose application. You should see output that includes Nginx startup messages.

To view logs for a specific service, specify its name:

docker compose logs web

Stopping Your Application

To stop your Docker Compose application without removing the containers, run:

docker compose stop

You should see output indicating that the containers are being stopped:

✔ Container docker-compose-test-web-1  Stopped

To verify that the containers are stopped, check their status:

docker compose ps

You should see that the containers are no longer running.

Starting Your Application Again

To start your stopped containers again, run:

docker compose start

You should see output indicating that the containers are being started:

✔ Container docker-compose-test-web-1  Started

Verify that they're running again:

docker compose ps

Stopping and Removing Your Application

When you're done with your Docker Compose application, you can stop and remove all containers, networks, and volumes with a single command:

docker compose down

You should see output similar to:

✔ Container docker-compose-test-web-1  Removed
✔ Network docker-compose-test_default  Removed

This indicates that your containers have been stopped and removed, and the network created for them has also been removed.

Troubleshooting Common Docker Compose Issues

This step is optional. You can skip it if you don't want to practice troubleshooting Docker Compose issues.

Even after resolving the "docker-compose: command not found" error, you might encounter other common issues with Docker Compose. Let's explore these issues and their solutions.

Issue 1: Conflicts with Existing Containers

Sometimes you might encounter errors like:

ERROR: for web  Cannot create container for service web: Conflict. The container name "/docker-compose-test-web-1" is already in use by container.

This happens when a container with the same name already exists. Let's see how to handle this:

1. First, check for any existing containers:

docker ps -a

This command lists all containers, including stopped ones.

2. If you see a container with a conflicting name, you can remove it:

docker rm -f docker-compose-test-web-1

Replace docker-compose-test-web-1 with the actual container name from your output.

Issue 2: Permission Denied Errors

Sometimes you might see permission errors when working with Docker Compose. These often occur because Docker commands typically require root privileges. If you see an error like:

ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?

You might need to use sudo with your Docker Compose commands, or ensure your user is in the Docker group. To add your user to the Docker group:

sudo usermod -aG docker $USER

Note: This requires logging out and back in to take effect. For this lab, we can use sudo with our commands if needed.

Issue 3: Port Conflicts

If you see an error like:

ERROR: for web  Cannot start service web: driver failed programming external connectivity on endpoint: Bind for 0.0.0.0:8080 failed: port is already allocated

It means another service is already using port 8080. To resolve this:

1. Find what's using port 8080:

sudo lsof -i :8080

2. Either stop that service or modify your docker-compose.yml to use a different port:

nano docker-compose.yml

Change the port mapping from "8080:80" to something like "8081:80", then save and exit.

3. Start your Docker Compose application again:

docker compose up -d

Let's Practice Fixing a Port Conflict

Let's deliberately create a port conflict and resolve it:

1. Create a new Docker Compose project with the same port:

mkdir -p ~/project/another-test
cd ~/project/another-test
nano docker-compose.yml

2. Add the following content:

version: "3"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

Save and exit.

3. Start the new service:

docker compose up -d

4. Now, go back to your original project and try to start it:

cd ~/project/docker-compose-test
docker compose up -d

You should see a port conflict error.

5. Modify your original docker-compose.yml to use port 8081 instead:

nano docker-compose.yml

Change "8080:80" to "8081:80", save and exit.

6. Try starting it again:

docker compose up -d

Now both services should be running, one on port 8080 and another on port 8081.

7. Clean up by stopping and removing both projects:

docker compose down
cd ~/project/another-test
docker compose down

Summary

Congratulations on completing this lab on resolving the "docker-compose: command not found" error. You have successfully:

1. Verified Docker and Docker Compose installation status
2. Installed Docker Compose using different methods
3. Created and run a simple Docker Compose application
4. Learned essential Docker Compose commands for managing applications
5. Explored common Docker Compose issues and their solutions

These skills will be valuable as you work with multi-container Docker applications in the future. The troubleshooting techniques you've learned can be applied to many other Docker-related issues, making your development workflow smoother and more efficient.