Docker Compose を使った「zsh: command not found: docker-compose」のトラブルシューティング

Introduction

Docker Compose is an essential tool for managing multi-container Docker applications. This lab will guide you through resolving the common "zsh: command not found: docker-compose" error that many users encounter when getting started with Docker Compose.

By completing this lab, you will learn how to properly install Docker Compose, troubleshoot path-related issues, and use Docker Compose to run a simple multi-container application. These skills are fundamental for developers working with containerized applications.

Skills Graph

Understanding Docker and Docker Compose

Before we start troubleshooting, let us understand what Docker Compose is and why it is important in the Docker ecosystem.

What is Docker?

Docker is a platform that enables developers to build, package, and run applications in containers. Containers are lightweight, isolated environments that include everything needed to run an application - code, runtime, system tools, libraries, and settings.

What is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. With Docker Compose, you use a YAML file to configure your application's services, networks, and volumes. Then, with a single command, you can create and start all the services from your configuration.

Let us check if Docker is properly installed on our system:

docker --version

You should see output similar to this:

Docker version 20.10.21, build baeda1f

This confirms that Docker is installed and ready to use. Now, let us try to run Docker Compose to see if it is installed:

docker-compose --version

If Docker Compose is not installed, you will see the error:

zsh: command not found: docker-compose

This error message is the focus of our lab - we will troubleshoot and fix this issue in the next steps.

Why Use Docker Compose?

Docker Compose offers several advantages for managing multi-container applications:

1. Simplifies Configuration: Define your entire application stack in a single YAML file
2. Ensures Consistency: Run the same application setup across multiple environments
3. Manages Dependencies: Handle service startup order and communication between containers
4. Improves Productivity: Save time with simple commands to manage your entire application lifecycle

In the next step, we will install Docker Compose and resolve the "command not found" error.

Installing Docker Compose

Now that we understand what Docker Compose is, let us install it on our system to resolve the "command not found" error.

Download Docker Compose Binary

The first step is to download the Docker Compose binary. The official Docker Compose binary is available on GitHub. We will use the curl command to download it:

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

This command downloads the Docker Compose binary that matches your operating system architecture and saves it to /usr/local/bin/docker-compose. The command will take a moment to execute as it downloads the file.

Make Docker Compose Executable

After downloading the binary, we need to make it executable:

sudo chmod +x /usr/local/bin/docker-compose

This command grants execution permissions to the Docker Compose binary.

Verify the Installation

Now, let us verify that Docker Compose has been installed correctly:

docker-compose --version

You should see output similar to this:

Docker Compose version v2.17.2

If you still see the "command not found" error, it means that the /usr/local/bin directory might not be in your system's PATH. We will address this issue in the next step.

Understanding the PATH Variable

The PATH variable is an environment variable in Linux that tells the shell which directories to search for executable files when you run a command. To view your current PATH, run:

echo $PATH

You should see a list of directories separated by colons (:). If /usr/local/bin is not in this list, that could explain why the shell cannot find the docker-compose command.

In the next step, we will troubleshoot and resolve any remaining issues that might prevent us from using Docker Compose.

Troubleshooting the "Command Not Found" Error

If you are still encountering the "zsh: command not found: docker-compose" error after installation, let us troubleshoot some common causes and their solutions.

Solution 1: Create a Symbolic Link

One common solution is to create a symbolic link to the Docker Compose binary in a directory that is definitely in your PATH, such as /usr/bin:

sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

This command creates a symbolic link (shortcut) to the Docker Compose binary in the /usr/bin directory, which is typically included in the system's PATH by default.

After creating the symbolic link, try running Docker Compose again:

docker-compose --version

You should now see the Docker Compose version information without any errors.

Solution 2: Use Docker Compose Plugin (Alternative Method)

In newer versions of Docker, Compose is available as a plugin. If you prefer to use this method instead, you can try:

docker compose version

Note the absence of a hyphen between docker and compose. If this command works, it means Docker Compose is available as a plugin, and you can use it with this syntax instead.

Solution 3: Add Docker Compose to Your PATH

If you prefer to keep Docker Compose in its current location but the symbolic link does not work, you can add the directory to your PATH manually:

echo 'export PATH=$PATH:/usr/local/bin' >> ~/.zshrc
source ~/.zshrc

This adds /usr/local/bin to your PATH and immediately applies the changes to your current session.

Verification

Regardless of which solution you used, verify that Docker Compose is now working correctly:

docker-compose --version

You should see output similar to:

Docker Compose version v2.17.2

Now that we have successfully installed and configured Docker Compose, in the next step we will create a simple Docker Compose project to test our installation.

Creating a Simple Docker Compose Project

Now that Docker Compose is properly installed and working, let us create a simple project to test our setup. We will create a basic web application with a web server and a Redis database.

Create a Project Directory

First, let us create a dedicated directory for our project:

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

Create a Docker Compose File

Now, let us create a docker-compose.yml file using the nano text editor:

nano docker-compose.yml

Copy and paste the following content into the file:

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

This Docker Compose file defines two services:

• web: An Nginx web server that will serve content from a local directory
• redis: A Redis database for caching or storing session data

Press Ctrl+O followed by Enter to save the file, then press Ctrl+X to exit nano.

Create HTML Content

Let us create a simple HTML page that our web service will serve:

mkdir -p html
nano html/index.html

Copy and paste the following content into the file:

<!DOCTYPE html>
<html>
  <head>
    <title>Docker Compose Test</title>
  </head>
  <body>
    <h1>Hello from Docker Compose!</h1>
    <p>If you can see this, your Docker Compose setup is working correctly.</p>
  </body>
</html>

Press Ctrl+O followed by Enter to save the file, then press Ctrl+X to exit nano.

Run the Docker Compose Project

Now, let us start our Docker Compose project:

docker-compose up -d

The -d flag runs the containers in the background (detached mode). You should see output similar to:

Creating network "docker-compose-test_default" with the default driver
Pulling web (nginx:alpine)...
Pulling redis (redis:alpine)...
[...]
Creating docker-compose-test_web_1   ... done
Creating docker-compose-test_redis_1 ... done

Verify the Services Are Running

Let us check that our services are running correctly:

docker-compose ps

You should see output similar to:

           Name                         Command               State          Ports
------------------------------------------------------------------------------------
docker-compose-test_redis_1   docker-entrypoint.sh redis ...   Up      6379/tcp
docker-compose-test_web_1     /docker-entrypoint.sh ngin ...   Up      0.0.0.0:8080->80/tcp

Access the Web Application

Now you can access the web application by opening a web browser in the LabEx interface and navigating to http://localhost:8080. You should see the "Hello from Docker Compose!" message.

Alternatively, you can use curl to check the web server from the command line:

curl http://localhost:8080

You should see the HTML content we created earlier.

Stop the Docker Compose Project

When you are finished testing, you can stop the Docker Compose project:

docker-compose down

You should see output similar to:

Stopping docker-compose-test_web_1   ... done
Stopping docker-compose-test_redis_1 ... done
Removing docker-compose-test_web_1   ... done
Removing docker-compose-test_redis_1 ... done
Removing network docker-compose-test_default

Congratulations! You have successfully installed Docker Compose, resolved the "command not found" error, and tested your setup with a simple multi-container application.

Summary

In this lab, you have learned how to:

1. Understand the role of Docker Compose in managing multi-container applications
2. Install Docker Compose on your system
3. Troubleshoot and resolve the "zsh: command not found: docker-compose" error
4. Create and run a simple multi-container application using Docker Compose

These skills provide a solid foundation for working with Docker and Docker Compose. You can now confidently use Docker Compose to define, deploy, and manage complex multi-container applications.

For further learning, consider exploring more advanced Docker Compose features such as environment variables, networks, volumes, and scaling services. You might also want to learn about Docker Compose in production environments and how to integrate it with CI/CD pipelines.