[IT-정보] 도커 컴포즈 설치 질문 정리 가이드 – 오류 해결과 설정 팁

도커 컴포즈 설치 질문 정리 가이드

분명히 강의를 보고 그대로 따라 했는데, 터미널에 명령어를 입력하자마자 command not found라는 빨간 글씨가 뜬 적이 있나요? 도커 엔진은 잘 설치된 것 같은데, 왜 하필 컨테이너를 여러 개 띄울 때 쓰는 도커 컴포즈만 말썽인지 답답할 때가 많을 거예요. 입문 단계에서는 설치 경로 하나, 권한 설정 하나 때문에 전체 실습이 막히는 일이 비일비재해요.

도커 컴포즈는 단순히 설치만 한다고 끝나는 게 아니에요. 운영체제마다 설치 방식이 다르고, 최근에는 기존의 방식과 새로운 방식이 혼재되어 있어서 무엇이 맞는지 헷갈리기 쉬워요. 환경 설정 하나를 잘못하면 나중에 컨테이너를 실행할 때마다 권한 오류를 마주하며 시간을 낭비하게 되죠.

이 글은 여러분이 겪고 있는 그 막막함을 해결해 드리기 위해 작성했어요. 설치 과정에서 흔히 발생하는 삽질을 줄이고, 한 번에 제대로 세팅을 끝낼 수 있도록 도와드릴게요. 이 글을 끝까지 읽고 나면 더 이상 설치 문제로 커뮤니티를 헤매지 않아도 돼요.

이 글에서 다루는 핵심 내용은 다음과 같아요.

• 설치 전 반드시 확인해야 하는 환경 조건
• 운영체제별(Linux, Windows, macOS) 최적의 설치 경로
• 설치 후 반드시 체크해야 할 명령어와 권한 설정
• 실제 실무에서 자주 발생하는 오류와 해결 방법

설치 전 반드시 체크해야 할 것들

도커 컴포즈를 설치하기 전에 무턱대고 명령어부터 입력하는 건 위험해요. 먼저 내 컴퓨터 환경이 무엇인지, 그리고 내가 설치하려는 방식이 현재 표준에 맞는지 확인해야 하거든요. 준비 없이 시작했다가는 이미 설치된 다른 프로그램과 충돌이 나거나, 설치를 완료해도 정작 실행이 안 되는 상황이 벌어질 수 있어요.

가장 먼저 확인해야 할 것은 도커 엔진(Docker Engine)의 설치 여부예요. 도커 컴포즈는 독립적으로 돌아가는 프로그램이 아니라, 도커 엔진 위에서 동작하는 플러그인 형태이기 때문이죠. 엔진이 없으면 컴포즈는 아무런 힘도 쓰지 못하는 빈 껍데기에 불과해요.

또한, 사용 중인 운영체제의 아키텍처도 매우 중요해요. 인텔이나 AMD 프로세서를 사용하는 x86_64 환경인지, 아니면 애플 실리콘(M1, M2 등) 같은 ARM 환경인지에 따라 다운로드해야 할 파일이 완전히 다르거든요. 이를 잘못 선택하면 설치 파일 자체가 실행되지 않아요.

환경에 따른 설치 방식 비교

위 표에서 볼 수 있듯이 리눅스 환경은 조금 더 까다로운 과정이 필요해요. 특히 사용자 권한 설정을 빼먹으면 매번 명령어 앞에 sudo를 붙여야 하는 번거로움이 생기니 주의해야 해요. 반면 윈도우나 맥은 도커 데스크탑 하나로 해결되지만, 컴퓨터 사양이 낮다면 실행 속도가 매우 느려질 수 있다는 점을 미리 염두에 두세요.

단계별 도커 컴포즈 설치 및 설정 방법

이제 본격적으로 설치를 시작해 볼게요. 환경에 따라 방법이 다르니, 본인이 사용 중인 운영체제 섹션을 찾아 차근차근 따라오시면 돼요. 중간에 명령어를 오타 내지 않도록 주의하며 진행해 주세요.

STEP 1. Linux 환경에서 패키지 매니저로 설치하기

리눅스 사용자라면 가장 깔끔하고 관리하기 쉬운 방법은 공식 저장소를 이용하는 거예요. 이 방법을 사용하면 나중에 도커를 업데이트할 때 컴포즈도 함께 관리할 수 있어 편리해요. Ubuntu를 기준으로 설명해 드릴게요.

먼저 시스템의 패키지 목록을 최신 상태로 업데이트해야 해요. 터미널을 열고 sudo apt update를 입력하세요. 그다음 도커 관련 필수 패키지들을 설치해요. sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin 명령어를 입력하면 도커 엔진과 함께 컴포즈 플러그인이 한 번에 설치돼요.

설치가 끝났다면 docker compose version을 입력해서 버전 정보가 잘 나오는지 확인해 보세요. 만약 명령어를 찾을 수 없다고 나온다면, 설치 과정에서 오류가 있었거나 패키지 이름이 환경마다 다를 수 있으니 다시 한번 확인이 필요해요.

STEP 2. Linux에서 바이너리 파일로 직접 설치하기

만약 패키지 매니저를 사용할 수 없는 환경이거나, 특정 버전을 직접 지정해서 설치해야 한다면 바이너리 다운로드 방식을 써야 해요. 이 방법은 조금 더 ‘개발자스러운’ 방식이지만, 경로 설정을 직접 해줘야 해서 주의가 필요해요.

먼저 현재 내 시스템의 아키텍처를 확인하세요. uname -m 명령어를 쳤을 때 x86_64가 나오면 일반적인 PC용이고, aarch64가 나오면 ARM 기반 서버예요. 그 후, 도커 공식 GitHub에서 최신 버전의 다운로드 링크를 복사해서 curl 명령어로 내려받아야 해요.

다운로드한 파일을 /usr/local/bin/docker-compose 경로로 옮기고, 실행 권한을 주는 sudo chmod +x /usr/local/bin/docker-compose 명령어를 반드시 실행해야 해요. 이 단계를 건너뛰면 파일은 있지만 실행할 수 없는 상태가 되어 버려요.

STEP 3. Windows 및 macOS에서 Docker Desktop 설치하기

개인 학습자나 일반 개발자라면 고민할 것 없이 Docker Desktop을 설치하는 것이 가장 빠르고 확실해요. 윈도우와 맥 모두 설치 과정이 매우 유사하거든요.

먼저 도커 공식 홈페이지에 접속해서 본인의 OS에 맞는 설치 파일을 내려받으세요. 윈도우 사용자의 경우, 설치 과정 중에 WSL 2(Windows Subsystem for Linux) 사용 옵션이 나오면 반드시 체크하는 것을 추천해요. WSL 2를 사용해야 리눅스 환경과 유사한 속도와 안정성을 누릴 수 있거든요. 설치가 끝나면 컴퓨터를 재부팅해야 할 수도 있어요.

맥 사용자는 설치 후 설정(Settings) 메뉴에서 Use Docker Compose V2 옵션이 활성화되어 있는지 확인만 하면 돼요. 도커 데스크탑은 설치와 동시에 도커 엔진과 컴포즈를 모두 포함하고 있기 때문에, 별도의 추가 설치 작업이 필요 없다는 게 가장 큰 장점이에요.

STEP 4. 권한 문제 해결을 위한 사용자 그룹 설정

리눅스에서 설치를 마쳤는데, 실행할 때마다 permission denied라는 메시지가 나온다면? 이건 현재 로그인한 사용자가 도커 엔진에 접근할 권한이 없어서 발생하는 문제예요. 매번 sudo를 붙이는 건 매우 비효리적이죠.

이 문제를 근본적으로 해결하려면 현재 사용자를 docker 그룹에 추가해야 해요. 터미널에 sudo usermod -aG docker $USER를 입력하세요. 여기서 $USER는 현재 로그인된 사용자 이름을 자동으로 불러오는 환경 변수예요. 명령어를 입력한 후에는 반드시 로그아웃했다가 다시 로그인하거나, newgrp docker 명령어를 입력해서 변경된 그룹 설정을 적용해야 해요.

STEP 5. 설치 완료 검증 및 실전 테스트

모든 과정이 끝났다면, 실제로 잘 동작하는지 확인해 봐야겠죠? 가장 쉬운 방법은 아주 간단한 docker-compose.yml 파일을 하나 만드는 거예요. 메모장을 열어 아래 내용을 복사해서 붙여넣고 파일을 저장하세요.

파일이 저장된 폴더에서 터미널을 열고 docker compose up -d를 입력해 보세요. 잠시 후 브라우저를 열고 localhost:8080에 접속했을 때 ‘Welcome to nginx!’라는 메시지가 보인다면, 여러분은 이제 완벽하게 도커 컴포즈를 사용할 준비가 된 거예요!

자주 하는 실수와 해결법

설치 과정에서 가장 많이 발생하는 실수들을 모아봤어요. 비슷한 상황을 겪고 있다면 아래 내용을 확인해서 바로 해결해 보세요.

• ❌ 명령어를 쳤는데 ‘command not found’가 떠요.
  왜 발생하는가: 설치가 안 되었거나, 실행 파일이 있는 경로(PATH)가 설정되지 않았기 때문이에요.
  ✅ 해결법: 리눅스라면 설치 경로를 확인하고, 윈도우/맥이라면 도커 데스크탑이 실행 중인지 확인하세요.
• ❌ 실행할 때마다 ‘sudo’를 붙여야 해요.
  왜 발생하는가: 현재 사용자가 docker 그룹에 포함되지 않아 권한이 없기 때문이에요.
  ✅ 해결법: sudo usermod -aG docker $USER 명령어로 그룹에 추가한 뒤 재로그인하세요.
• ❌ ‘docker-compose’는 되는데 ‘docker compose’는 안 돼요.
  왜 발생하는가: 구형 방식(V1)과 신형 방식(V2)이 혼재되어 있는 상태예요.
  ✅ 해결법: 가급적 최신 표준인 docker compose(띄어쓰기 포함)를 사용하도록 설정을 맞추는 게 좋아요.
• ❌ 포트 충돌 오류(Port already in use)가 발생해요.
  왜 발생하는가: 이미 다른 프로그램이나 이전 컨테이너가 해당 포트를 쓰고 있기 때문이에요.
  ✅ 해결법: docker ps로 실행 중인 컨테이너를 확인하거나, docker-compose.yml에서 포트 번호를 변경하세요.
• ❌ YAML 파일 형식이 잘못되었다고 나와요.
  왜 발생하는가: YAML은 들여쓰기(Space)에 매우 민감한 언어예요.
  ✅ 해결법: 탭(Tab) 대신 반드시 공백(Space) 2칸 또는 4칸을 사용하여 들여쓰기를 통일하세요.

자주 묻는 질문

Q. 도커 데스크탑을 설치하면 컴포즈도 자동으로 설치되나요?

네, 맞아요. 도커 데스크탑은 엔진, CLI, 컴포즈를 모두 포함하는 패키지 형태예요. 별도로 설치할 필요 없이 바로 사용하시면 됩니다.

Q. V1과 V2의 차이가 정확히 무엇인가요?

V1은 파이썬으로 작성된 별도의 프로그램이었고, V2는 도커 엔진의 일부로 통합된 플러그인이에요. V2가 훨씬 빠르고 도커의 다른 명령어들과 일관성 있게 작동하기 때문에 지금은 무조건 V2를 쓰는 게 유리해요.

Q. 설치된 컴포즈 버전을 확인하는 방법은요?

터미널에 docker compose version을 입력하면 현재 설치된 버전을 바로 확인할 수 있어요.

Q. 리눅스 서버에서 컴포즈를 업데이트하려면 어떻게 하나요?
패키지 매니저로 설치했다면 sudo apt update && sudo apt upgrade를 통해 도커 패키지 전체를 업데이트하면 컴포즈도 함께 올라가요. 바이너리로 설치했다면 새 버전을 다시 다운로드해서 덮어쓰면 됩니다.

Q. 윈도우에서 WSL 2를 꼭 써야 하나요?
꼭 그래야 하는 건 아니지만, 성능 면에서 차이가 커요. WSL 2를 쓰지 않으면 윈도우 자체 가상화 계층을 거쳐야 해서 컨테이너 실행 속도가 훨씬 느려질 수 있어요.

마무리하며: 다음 단계로 나아가기

도커 컴포즈 설치를 성공적으로 마치신 것을 진심으로 축하드려요! 이제 여러분은 여러 개의 서비스를 하나의 설정 파일로 제어할 수 있는 강력한 무기를 갖게 되었어요. 처음에는 복잡해 보이지만, 한 번 익숙해지면 컨테이너 운영이 얼마나 편해지는지 체감하게 될 거예요.

설치가 끝났다면 이제 다음 단계로 나아갈 차례예요. 단순히 설치에 머물지 말고, 실제 서비스 환경을 구축해 보는 연습이 필요해요.

이번 주에 해볼 일:

• docker-compose.yml 파일을 직접 작성해서 DB와 웹 서버를 동시에 띄워보기
• docker compose down 명령어로 컨테이너를 안전하게 정리하는 법 익히기
• 컨테이너 로그를 확인하는 docker compose logs -f 명령어 연습하기

혹시 설치 과정 중에 제가 언급하지 않은 다른 오류가 발생했나요? 그렇다면 주저하지 말고 댓글로 질문을 남겨 주세요. 여러분이 겪은 시행착오를 정리해서 다음 가이드에 꼭 포함하도록 할게요. 함께 공부하며 성장해 나가요!

도커의 기초를 더 탄탄히 다지고 싶다면, 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글도 함께 읽어보시는 것을 추천드려요.