[IT-정보] 도커 컴포즈 설치 오류 해결 가이드 – 장애 대응을 위한 원인별 진단과 해결법

도커 컴포즈 설치 오류, 왜 반복될까요?

새로운 서버를 구축하거나 컨테이너 환경을 재구축할 때 가장 당혹스러운 순간 중 하나예요. 분명히 가이드대로 명령어를 입력했는데 command not found라는 메시지가 뜨거나, 권한 문제로 실행조차 되지 않을 때의 막막함은 운영자라면 누구나 공감할 거예요.

단순히 명령어를 한 번 더 입력한다고 해결될 문제가 아니에요. 도커 컴포즈 설치 오류는 시스템 아키텍처, 환경 변수 설정, 권한 관리, 혹은 도커 엔진과의 버전 호환성 등 매우 다양한 원인이 복합적으로 얽혀 있어요. 특히 최근에는 도커 컴포즈가 독립된 바이너리 방식에서 도커 CLI 플러그인 방식으로 변화하면서, 기존 방식대로 설치하려는 과정에서 혼선이 잦아지고 있어요.

이런 오류를 방치하면 컨테이너 운영 전체가 마비될 수 있어요. 장애 대응을 맡은 운영자에게는 단순히 ‘설치를 성공시키는 것’보다 왜 오류가 났는지 정확히 진단하고 재발을 막는 능력이 훨씬 중요해요. 오늘 이 글에서는 단순 설치를 넘어, 실무에서 바로 써먹을 수 있는 트러블슈팅 프로세스를 정리해 드릴게요.

이 글을 통해 얻을 수 있는 정보는 다음과 같아요.

• 설치 전 반드시 확인해야 할 시스템 환경 체크리스트
• 바이너리 방식과 플러그인 방식의 차이점과 선택 기준
• 단계별 설치 과정에서 발생하는 핵심 오류와 해결 명령어
• 실무에서 자주 마주하는 5가지 주요 트러블슈팅 사례
• 설치 완료 후 안정적인 운영을 위한 환경 설정법

설치 전 반드시 확인해야 할 환경 체크리스트

도커 컴포즈를 설치하기 전에 아무런 준비 없이 명령어부터 입력하는 것은 위험해요. 설치 환경이 갖춰지지 않은 상태에서 시도하는 작업은 시간 낭비일 뿐만 아니라, 시스템 설정에 꼬임을 유발할 수 있어요. 가장 먼저 도커 엔진(Docker Engine)이 정상적으로 구동 중인지 확인하는 것이 필수예요. 도커 컴포즈는 도커 엔진 위에서 동작하는 도구이기 때문이에요.

또한, 현재 사용 중인 서버의 OS 종류와 아키텍처를 정확히 알아야 해요. x86_64 기반의 일반적인 서버인지, 아니면 AWS Graviton이나 Apple Silicon 기반의 ARM 아키텍처인지에 따라 다운로드해야 할 파일이 완전히 달라져요. 아키텍처를 잘못 선택하면 아무리 명령어를 잘 입력해도 실행 파일이 작동하지 않아요.

다음은 설치 방식에 따른 비교표예요. 본인의 운영 환경에 맞는 방식을 미리 선택해 두면 시행착오를 크게 줄일 수 있어요.

운영 환경이 최신 표준을 따르고 있다면 CLI 플러그인 방식을 선택하는 것이 관리에 훨씬 유리해요. 하지만 기존에 작성된 배포 스크립트나 CI/CD 파이프라인이 docker-compose(하이픈 포함) 형식을 요구한다면 바이너리 설치 방식을 고려해야 해요.

실무 중심 도커 컴포즈 설치 단계별 실행 가이드

이제 본격적으로 설치를 진행해 볼게요. 가장 안정적이고 범용적인 두 가지 방식인 바이너리 직접 설치와 CLI 플러그인 설치 과정을 상세히 나누어 설명할게요. 각 단계에서 무엇을 왜 하는지 이해하는 것이 중요해요.

STEP 1. 시스템 아키텍처와 현재 도커 버전 확인하기

설치를 시작하기 전, 현재 서버의 상태를 정확히 파악해야 해요. 잘못된 파일을 다운로드하는 실수를 방지하기 위해서예요. 먼저 시스템 아키텍처를 확인하세요.

uname -m 명령어를 입력하여 결과값을 기록해 두세요. x86_64라면 일반적인 리눅스 서버이고, aarch64라면 ARM 기반 서버예요. 그다음은 현재 설치된 도커 엔진의 버전을 확인해야 해요. docker version 명령어를 사용하세요. 도커 엔진 버전이 너무 낮으면 최신 컴포즈 플러그인이 정상적으로 연동되지 않을 수 있어요.

STEP 2. 바이너리 파일 직접 다운로드 및 배치하기

기존의 docker-compose 명령어를 그대로 사용하고 싶다면 이 방식을 따라야 해요. GitHub의 공식 릴리스 페이지에서 최신 버전을 가져오는 과정이에요.

먼저 아래와 같은 형식의 명령어를 사용해 다운로드를 진행해요. 이때 주의할 점은 URL에 자신의 아키텍처 정보를 정확히 넣어야 한다는 거예요. 예를 들어 x86_64 환경이라면 다음과 같이 입력해요.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.1/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose

여기서 -L 옵션은 매우 중요해요. GitHub 릴리스 파일은 리다이렉션(Redirection)을 사용하는 경우가 많기 때문에, 이 옵션을 빼먹으면 파일 내용이 아닌 HTML 안내 페이지가 다운로드되어 실행이 불가능해져요. 다운로드가 완료되면 파일이 제대로 생성되었는지 ls -l /usr/local/bin/docker-compose로 확인하세요.

STEP 3. 실행 권한 부여 및 경로(PATH) 설정

파일을 다운로드만 했다고 해서 바로 사용할 수 있는 것은 아니에요. 리눅스 시스템은 다운로드된 파일에 ‘실행 권한’이 있어야 이를 프로그램으로 인식해요. 이 단계를 건너뛰면 Permission denied 오류를 만나게 돼요.

다음 명령어를 통해 실행 권한을 부여하세요.

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

이제 명령어가 어디서든 실행될 수 있도록 경로를 확인해야 해요. 보통 /usr/local/bin은 시스템의 기본 PATH에 포함되어 있지만, 만약 명령어를 입력했는데도 찾을 수 없다고 나온다면 echo $PATH를 입력해 해당 경로가 포함되어 있는지 확인하세요. 포함되어 있지 않다면 ~/.bashrc나 /etc/profile 파일에 경로를 추가해야 해요.

STEP 4. 최신 방식인 Docker CLI 플러그인으로 설치하기

최근 데브옵스 환경에서는 이 방식을 훨씬 더 권장해요. 도커 명령어의 일부로 컴포즈를 사용하는 방식이라 관리가 매우 깔끔해요. 설치 과정은 바이너리와 조금 달라요.

먼저 플러그인이 저장될 디렉토리를 생성해야 해요. mkdir -p ~/.docker/cli-plugins 명령어를 사용하세요. 그다음, 앞서 했던 방식과 유사하게 파일을 다운로드하되, 목적지를 플러그인 폴더로 지정해야 해요.

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

이 방식의 장점은 도커 명령어를 쓸 때 docker compose(하이픈 없이 띄어쓰기)로 자연스럽게 이어진다는 점이에요. 설치가 끝난 후 docker compose version을 입력해 결과가 잘 나온다면 성공이에요.

STEP 5. 설치 확인 및 최종 테스트

모든 설치가 끝났다면 반드시 실제 동작 여부를 테스트해야 해요. 단순히 버전만 확인하는 것을 넘어, 아주 작은 규모의 컨테이너를 띄워보는 것이 가장 확실해요.

간단한 docker-compose.yml 파일을 하나 만들어서 테스트해 보세요. 예를 들어 nginx 이미지를 사용하는 파일을 만들고 docker compose up -d를 실행했을 때, 컨테이너가 정상적으로 Running 상태로 올라오면 모든 설치 과정이 완벽하게 완료된 것이에요.

자주 하는 실수와 해결법

설치 과정에서 가장 빈번하게 발생하는 문제들을 정리했어요. 문제가 발생했을 때 당황하지 말고 아래 사례 중 본인에게 해당하는 것이 있는지 확인해 보세요.

• ❌ command not found (명령어를 찾을 수 없음)
  → 왜 발생하는가: 파일이 설치되지 않았거나, 실행 파일이 있는 경로가 시스템 PATH에 등록되지 않았기 때문이에요.
  → ✅ 해결법: ls -l /usr/local/bin/docker-compose로 파일 존재를 확인하고, 없다면 다시 다운로드하세요. 있다면 echo $PATH로 경로를 확인하세요.
• ❌ permission denied (권한 거부)
  → 왜 발생하는가: 실행 권한(x)이 없거나, 시스템 디렉토리에 접근할 권한이 없기 때문이에요.
  → ✅ 해결법: sudo chmod +x [파일경로]를 통해 실행 권한을 부여하거나, 명령어 앞에 sudo를 붙여서 실행하세요.
• ❌ exec format error (실행 형식 오류)
  → 왜 발생하는가: 시스템 아키텍처(x86_64 vs ARM)와 맞지 않는 바이너리 파일을 다운로드했기 때문이에요.
  → ✅ 해결법: uname -m으로 아키텍처를 다시 확인하고, 그에 맞는 파일을 다시 다운로드하세요.
• ❌ docker: ‘compose’ is not a docker command
  → 왜 발생하는가: 도커 플러그인 방식으로 설치하지 않았거나, 플러그인 경로가 잘못 지정되었기 때문이에요.
  → ✅ 해결법: 플러그인 파일을 ~/.docker/cli-plugins 폴더에 정확히 넣었는지 확인하세요.
• ❌ cannot connect to the Docker daemon
  → 왜 발생하는가: 도커 엔진 자체가 실행 중이 아니거나, 사용자가 도커 소켓에 접근할 권한이 없기 때문이에요.
  → ✅ 해결법: sudo systemctl start docker로 엔진을 켜고, 사용자를 docker 그룹에 추가하세요.

자주 묻는 질문

Q. docker-compose와 docker compose의 차이가 무엇인가요?

명령어의 형태와 설치 방식의 차이에요. 하이픈이 들어간 docker-compose는 별도의 바이너리 프로그램을 실행하는 방식이고, 띄어쓰기가 있는 docker compose는 도커 엔진의 플러그인으로서 동작하는 방식이에요. 현재는 후자인 플러그인 방식이 표준이에요.

Q. 설치를 완료했는데 업데이트는 어떻게 하나요?

바이너리 방식이라면 새 버전의 파일을 다시 다운로드하여 기존 파일을 덮어씌우면 돼요. 플러그인 방식이라면 도커 엔진을 업데이트할 때 함께 관리되거나, 동일하게 플러그인 폴더의 파일을 교체하면 된답니다.

Q. Ubuntu 환경에서 패키지 매니저로 설치할 수 없나요?
sudo apt-get install docker-compose-plugin 명령어를 통해 공식 레포지토리가 등록되어 있다면 매우 간편하게 설치할 수 있어요. 가장 권장하는 방법 중 하나예요.

Q. ARM 기반 서버(M1/M2 Mac, AWS Graviton)에서도 작동하나요?
네, 당연히 작동해요. 다만 다운로드 시 파일명 끝에 aarch64 또는 arm64가 붙은 파일을 선택해야 한다는 점만 기억해 주세요.

Q. 설치 중에 네트워크 오류가 발생하면 어떻게 하죠?
서버가 외부 인터넷(GitHub)에 접속 가능한지 확인하세요. 프록시 환경이라면 curl -x [프록시주소] 옵션을 사용하여 다운로드해야 해요.

성공적인 컨테이너 운영을 위한 마무리

도커 컴포즈 설치 과정에서 겪은 오류들은 사실 서버 운영을 하면서 마주칠 수 있는 아주 기초적인 문제들이에요. 이 과정들을 통해 시스템의 아키텍처, 권한 체계, 그리고 환경 변수의 중요성을 다시 한번 체득하셨을 거라고 믿어요. 설치에 성공했다면, 이제는 안정적으로 컨테이너를 관리할 차례예요.

오늘 바로 실천할 수 있는 다음 단계들을 제안해 드릴게요.

• 오늘 할 일: 현재 운영 중인 서버의 아키텍처와 도커 버전을 체크하고 설치 방식을 결정하세요.
• 이번 주 할 일: 결정한 방식으로 설치를 완료하고, 기존 서비스들이 정상적으로 작동하는지 모니터링하세요.
• 실행 직전 할 일: 만약의 사태를 대비해 설치 명령어를 메모장이나 팀 위키에 정리해 두세요.

만약 같은 오류가 반복된다면, 오늘 배운 진단 순서를 체크리스트로 만들어 두는 것이 가장 좋은 대응책이에요. 같은 문제를 두 번 겪지 않는 것이 진정한 전문가의 자세니까요.

도커 컴포즈 설치와 관련된 더 깊은 이해가 필요하다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드를 함께 읽어보시는 것을 추천드려요.