'docker-compose: command not found' 오류 해결 방법 - Docker Compose 설치 및 문제 해결 가이드

소개

이 랩은 Docker 사용자들이 흔히 겪는 문제인 "docker-compose: command not found" 오류를 해결하는 실질적인 가이드를 제공합니다. Docker Compose 는 멀티 컨테이너 Docker 애플리케이션을 관리하는 데 필수적인 도구이며, 이 오류가 발생하면 워크플로우에 지장을 줄 수 있습니다. 이 랩을 완료함으로써, 이 문제를 해결하고 수정하는 기술을 습득하여 컨테이너화된 애플리케이션을 효과적으로 개발하고 배포하는 데 도움이 될 것입니다.

docker compose command not found

이 랩은 학습을 위해 인터넷 연결이 필요하므로, Pro 사용자만 VM 을 시작할 수 있습니다. 계정을 Pro 로 업그레이드하세요.

Docker Compose 이해 및 설치 확인

Docker Compose 란 무엇인가?

Docker Compose 는 멀티 컨테이너 애플리케이션을 정의하고 공유하는 데 도움이 되는 도구입니다. Compose 를 사용하면 애플리케이션의 서비스를 구성하는 YAML 파일을 생성한 다음, 단일 명령으로 모든 서비스를 시작할 수 있습니다. 함께 작동하는 여러 컨테이너를 관리하는 프로세스를 단순화합니다.

Docker Compose 설치 확인

먼저 Docker Compose 가 시스템에 이미 설치되어 있는지 확인해 보겠습니다. 터미널을 열고 다음 명령을 실행합니다.

docker-compose --version

다음과 유사한 출력을 볼 수 있습니다.

docker-compose: command not found

command not found

하지만 docker-compose: command not found와 같은 오류 메시지가 표시되면 Docker Compose 가 설치되지 않았거나 시스템의 PATH 에 제대로 구성되지 않았음을 의미합니다.

Docker 설치 확인

Docker Compose 를 설치하기 전에 Docker 자체가 제대로 설치되었는지 확인해 보겠습니다. 다음 명령을 실행합니다.

docker --version

다음과 유사한 출력을 볼 수 있습니다.

Docker version 20.10.21, build 20.10.21-0ubuntu1~22.04.3

이 출력이 표시되지 않으면 Docker 가 제대로 설치되지 않았을 수 있습니다. 하지만 이 랩에서는 Docker Compose 문제 해결에 집중하겠습니다.

Docker Compose 설치

Docker Compose 가 설치되지 않았거나 접근할 수 없음을 확인했으므로, 설치해 보겠습니다. Docker Compose 를 설치하는 몇 가지 방법이 있지만, Ubuntu 시스템에 가장 간단한 방법에 집중하겠습니다.

방법 1: apt 패키지 관리자 사용

Docker Compose 를 설치하는 가장 간단한 방법은 apt 패키지 관리자를 사용하는 것입니다. 다음 단계를 따르세요.

먼저, 저장소를 설정하고 종속성을 설치합니다.

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

업데이트 프로세스를 보여주는 출력을 볼 수 있습니다.

다음으로, Docker Compose 를 설치합니다.

sudo apt install -y docker-compose-plugin

설치 진행 상황을 보여주는 출력을 볼 수 있습니다.

설치가 완료된 후, 버전을 확인하여 제대로 작동하는지 확인합니다.

docker compose version

참고: 최신 Docker 설치에서는 명령어가 docker-compose (하이픈 포함) 대신 docker compose (공백 포함) 입니다.

다음과 유사한 출력을 볼 수 있습니다.

Docker Compose version v2.33.1

방법 2: curl 을 사용하여 특정 버전 설치

apt 방법을 사용하여 이미 Docker Compose 를 설치한 경우 이 방법은 건너뛸 수 있습니다.

apt 방법이 작동하지 않거나 특정 버전이 필요한 경우, Docker Compose 를 직접 설치할 수 있습니다.

Docker CLI 플러그인용 디렉토리를 생성합니다 (존재하지 않는 경우).

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

Docker Compose 바이너리를 다운로드합니다.

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

파일이 다운로드되는 동안 진행률 표시줄을 볼 수 있습니다.

바이너리를 실행 가능하게 만듭니다.

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

설치를 확인합니다.

docker compose version

Docker Compose 버전을 보여주는 출력을 볼 수 있습니다.

간단한 Docker Compose 프로젝트 생성

Docker Compose 를 성공적으로 설치했으므로, 모든 것이 제대로 작동하는지 확인하기 위해 간단한 Docker Compose 프로젝트를 만들어 보겠습니다.

프로젝트 디렉토리 생성

먼저, Docker Compose 프로젝트를 위한 디렉토리를 생성해 보겠습니다.

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

Docker Compose 파일 생성

이제, 기본적인 Nginx 웹 서버를 실행하는 간단한 Docker Compose 파일을 만들어 보겠습니다. nano 텍스트 편집기를 사용하여 docker-compose.yml이라는 파일을 생성합니다.

nano docker-compose.yml

편집기에서 다음 내용을 추가합니다.

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

이 구성은 다음을 정의합니다.

최신 Nginx 이미지를 사용하는 "web"이라는 서비스
컨테이너의 포트 80 에서 호스트의 포트 8080 으로의 포트 매핑
로컬 디렉토리를 Nginx 웹 루트에 매핑하는 볼륨

Ctrl+O를 누른 다음 Enter를 눌러 파일을 저장하고, Ctrl+X를 눌러 nano 를 종료합니다.

HTML 콘텐츠 생성

html 디렉토리와 간단한 index.html 파일을 만들어 보겠습니다.

mkdir -p html
nano html/index.html

편집기에서 다음 HTML 콘텐츠를 추가합니다.

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

Ctrl+O를 누른 다음 Enter를 눌러 파일을 저장하고, Ctrl+X를 눌러 nano 를 종료합니다.

Docker Compose 프로젝트 실행

이제 Docker Compose 프로젝트를 실행해 보겠습니다.

docker compose up -d

-d 플래그는 컨테이너를 분리된 모드 (백그라운드) 로 실행합니다.

다음과 유사한 출력을 볼 수 있습니다.

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

이는 Docker Compose 가 컨테이너를 성공적으로 생성하고 시작했음을 나타냅니다.

웹 서버 확인

웹 서버가 제대로 실행되고 있는지 확인해 보겠습니다.

curl http://localhost:8080

이전에 생성한 HTML 콘텐츠를 볼 수 있습니다.

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

이는 Docker Compose 가 제대로 작동하고 있음을 확인합니다.

docker compose is working

Docker Compose 애플리케이션 관리

Docker Compose 애플리케이션을 성공적으로 설정하고 실행했으므로, 다양한 Docker Compose 명령을 사용하여 이를 관리하는 방법을 알아보겠습니다.

실행 중인 컨테이너 확인

Docker Compose 컨테이너의 상태를 확인하려면 다음을 실행합니다.

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

다음과 유사한 출력을 볼 수 있습니다.

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

이는 Nginx 웹 서버 컨테이너가 실행 중이며 포트 매핑이 활성화되어 있음을 보여줍니다.

컨테이너 로그 보기

컨테이너의 로그를 보려면 다음을 실행합니다.

docker compose logs

이렇게 하면 Docker Compose 애플리케이션의 모든 컨테이너에서 결합된 로그가 표시됩니다. Nginx 시작 메시지를 포함하는 출력을 볼 수 있습니다.

특정 서비스의 로그를 보려면 해당 이름을 지정합니다.

docker compose logs web

애플리케이션 중지

컨테이너를 제거하지 않고 Docker Compose 애플리케이션을 중지하려면 다음을 실행합니다.

docker compose stop

컨테이너가 중지되고 있음을 나타내는 출력을 볼 수 있습니다.

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

컨테이너가 중지되었는지 확인하려면 상태를 확인합니다.

docker compose ps

컨테이너가 더 이상 실행되지 않음을 볼 수 있습니다.

애플리케이션 다시 시작

중지된 컨테이너를 다시 시작하려면 다음을 실행합니다.

docker compose start

컨테이너가 시작되고 있음을 나타내는 출력을 볼 수 있습니다.

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

다시 실행 중인지 확인합니다.

docker compose ps

애플리케이션 중지 및 제거

Docker Compose 애플리케이션을 완료하면 단일 명령으로 모든 컨테이너, 네트워크 및 볼륨을 중지하고 제거할 수 있습니다.

docker compose down

다음과 유사한 출력을 볼 수 있습니다.

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

이는 컨테이너가 중지 및 제거되었고, 컨테이너를 위해 생성된 네트워크도 제거되었음을 나타냅니다.

일반적인 Docker Compose 문제 해결

이 단계는 선택 사항입니다. Docker Compose 문제 해결을 연습하고 싶지 않다면 건너뛸 수 있습니다.

"docker-compose: command not found" 오류를 해결한 후에도 Docker Compose 와 관련된 다른 일반적인 문제가 발생할 수 있습니다. 이러한 문제와 해결책을 살펴보겠습니다.

문제 1: 기존 컨테이너와의 충돌

때로는 다음과 같은 오류가 발생할 수 있습니다.

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

이는 동일한 이름을 가진 컨테이너가 이미 존재할 때 발생합니다. 이를 처리하는 방법을 살펴보겠습니다.

먼저, 기존 컨테이너가 있는지 확인합니다.

docker ps -a

이 명령은 중지된 컨테이너를 포함하여 모든 컨테이너를 나열합니다.

충돌하는 이름의 컨테이너가 보이면 제거할 수 있습니다.

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

docker-compose-test-web-1을 출력에서 실제 컨테이너 이름으로 바꿉니다.

문제 2: 권한 거부 오류

Docker Compose 로 작업할 때 때때로 권한 오류가 표시될 수 있습니다. 이러한 오류는 Docker 명령이 일반적으로 root 권한을 필요로 하기 때문에 자주 발생합니다. 다음과 같은 오류가 표시되면:

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

Docker Compose 명령에 sudo를 사용하거나 사용자가 Docker 그룹에 있는지 확인해야 할 수 있습니다. 사용자를 Docker 그룹에 추가하려면:

sudo usermod -aG docker $USER

참고: 이 작업은 적용하려면 로그아웃했다가 다시 로그인해야 합니다. 이 랩에서는 필요한 경우 명령에 sudo를 사용할 수 있습니다.

문제 3: 포트 충돌

다음과 같은 오류가 표시되면:

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

다른 서비스가 이미 포트 8080 을 사용하고 있음을 의미합니다. 이를 해결하려면:

포트 8080 을 사용하고 있는 항목을 찾습니다.

sudo lsof -i :8080

해당 서비스를 중지하거나 docker-compose.yml을 수정하여 다른 포트를 사용합니다.

nano docker-compose.yml

포트 매핑을 "8080:80"에서 "8081:80"과 같이 변경한 다음 저장하고 종료합니다.

Docker Compose 애플리케이션을 다시 시작합니다.

docker compose up -d

포트 충돌 해결 연습

의도적으로 포트 충돌을 만들고 해결해 보겠습니다.

동일한 포트를 사용하여 새 Docker Compose 프로젝트를 만듭니다.

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

다음 내용을 추가합니다.

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

저장하고 종료합니다.

새 서비스를 시작합니다.

docker compose up -d

이제 원래 프로젝트로 돌아가서 시작해 봅니다.

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

포트 충돌 오류가 표시되어야 합니다.

원래 docker-compose.yml 을 수정하여 대신 포트 8081 을 사용합니다.

nano docker-compose.yml

"8080:80"을 "8081:80"으로 변경하고 저장한 후 종료합니다.

다시 시작해 봅니다.

docker compose up -d

이제 두 서비스가 모두 실행되어야 하며, 하나는 포트 8080 에서, 다른 하나는 포트 8081 에서 실행됩니다.

두 프로젝트를 모두 중지하고 제거하여 정리합니다.

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

요약

"docker-compose: command not found" 오류 해결에 대한 이 랩을 완료하신 것을 축하드립니다. 다음을 성공적으로 수행했습니다.

Docker 및 Docker Compose 설치 상태 확인
다양한 방법으로 Docker Compose 설치
간단한 Docker Compose 애플리케이션 생성 및 실행
애플리케이션 관리를 위한 필수 Docker Compose 명령 학습
일반적인 Docker Compose 문제 및 해결책 탐색

이러한 기술은 향후 다중 컨테이너 Docker 애플리케이션으로 작업할 때 유용할 것입니다. 배운 문제 해결 기술은 다른 많은 Docker 관련 문제에 적용할 수 있어 개발 워크플로우를 더 원활하고 효율적으로 만들 수 있습니다.