왜 지금 도커 컴포즈 설치 방식을 고민해야 할까요
터미널에 docker-compose up 명령어를 입력했는데 “command not found”라는 메시지가 뜨는 순간, 당혹스러움이 밀려와요. 분명히 도커를 설치했는데 왜 컴포즈는 작동하지 않는 걸까요? 혹은 팀원 중 누구는 명령어가 작동하고 누구는 안 되는 상황을 겪어보셨을 거예요. 이런 문제는 단순히 명령어를 잘못 입력해서 발생하는 것이 아니라, 각자의 운영 체제와 목적에 맞지 않는 설치 방식을 선택했기 때문에 발생해요.
현대적인 컨테이너 운영 환경에서는 단순히 도구를 설치하는 것보다 어떤 방식으로 설치하느냐가 매우 중요해요. 로컬 개발 환경에서는 편의성이 우선이지만, 운영 서버에서는 자동화와 안정성이 최우선이기 때문이죠. 설치 방식에 따라 명령어의 형태가 바뀌기도 하고, 업데이트 관리 방법이 완전히 달라지기도 해요. 잘못된 선택은 나중에 CI/CD 파이프라인을 구축하거나 팀의 개발 환경을 표준화할 때 예상치 못한 비용으로 돌아와요.
이 글에서는 도커 컴포즈 설치 비교를 통해 여러분의 상황에 딱 맞는 해답을 찾아드려요. 단순히 설치 명령어를 나열하는 것이 아니라, 각 방식이 가진 구조적 차이와 실무적인 장단점을 깊이 있게 분석했어요. 이 글을 끝까지 읽고 나면, 여러분은 어떤 운영 체제를 마주하더라도 당황하지 않고 가장 효율적인 설치 경로를 결정할 수 있어요.
- 사용자 환경(OS)에 따른 대표적인 설치 대안 3가지
- 설치 방식별 성능, 관리 편의성, 자동화 가능성 비교
- 리눅스, 윈도우, 맥 환경별 단계별 실행 가이드
- 설치 후 흔히 발생하는 오류와 해결 방법
설치 전 반드시 확인해야 할 판단 기준
도커 컴포즈를 설치하기 전에 무작정 명령어를 입력하는 것은 위험해요. 먼저 본인이 처한 환경이 로컬 개발 환경인지, 아니면 운영 서버 환경인지를 명확히 구분해야 해요. 로컬 환경에서는 GUI(그래픽 사용자 인터페이스)가 제공되는 도구가 생산성을 높여주지만, 서버에서는 불필요한 리소스 소모를 줄이기 위해 최소한의 바이너리만 설치하는 것이 원칙이에요.
또한, 도커 컴포즈의 버전을 확인하는 것도 중요해요. 과거에 사용하던 V1(Python 기반) 방식과 현재 표준인 V2(Go 기반 CLI 플러그인) 방식은 사용법과 설치 경로가 완전히 달라요. 최근에는 도커 엔진의 명령어를 확장하는 플러그인 형태인 V2 사용을 강력히 권장하고 있어요. 따라서 설치를 시작하기 전에 현재 사용 중인 도커 엔진의 버전과 운영 체제의 아키텍처(x86_64 또는 ARM64)를 미리 파악해 두는 것이 좋아요.
아래 표는 설치 방식을 결정할 때 참고할 수 있는 핵심 기준이에요. 본인의 상황이 어디에 해당하는지 살펴보세요.
| Docker Desktop | CLI 플러그인 (V2) | Standalone 바이너리 | |
|---|---|---|---|
| 주요 타깃 | Windows/Mac 개발자 | Linux 서버/DevOps | 레거시/특수 환경 |
| 설치 난이도 | 매우 낮음 | 중간 (패키지 매니저) | 중간 (수동 설정) |
| 자동화 적합성 | 낮음 (GUI 중심) | 매우 높음 | 높음 |
| 리소스 점유 | 높음 (가상화 포함) | 매우 낮음 | 매우 낮음 |
단순히 “설치하기 쉽다”는 이유만으로 Docker Desktop을 선택했다가는, 실제 운영 서버로 코드를 옮겼을 때 환경 차이로 인한 환경 불일치 문제를 겪게 될 수 있어요. 따라서 로컬에서는 편의성을, 서버에서는 일관성을 기준으로 삼아야 해요. 이제 구체적인 실행 단계를 통해 각 방식의 실제 설치 과정을 살펴볼게요.
상황별 도커 컴포즈 최적 설치 단계
도커 컴포즈를 설치하는 방법은 크게 세 가지 경로로 나뉘어요. 각 경로는 사용자의 운영 체제와 목적에 따라 명확한 장단점을 가지고 있어요. 지금부터 단계별로 가장 권장되는 설치 방법을 상세히 안내해 드릴게요.
STEP 1. 개인 개발자를 위한 Docker Desktop 설치
Windows나 macOS를 사용하는 대부분의 개발자에게 가장 추천하는 방식이에요. Docker Desktop은 도커 엔진, Docker CLI, 그리고 Docker Compose를 하나의 패키지로 묶어서 제공하기 때문에 설치 과정이 매우 단순해요. 설치 프로그램(Installer)을 실행하기만 하면 모든 설정이 자동으로 완료돼요.
설치 과정은 다음과 같아요. 먼저 공식 홈페이지에서 OS에 맞는 설치 파일을 내려받으세요. 설치 중에 WSL 2(Windows Subsystem for Linux) 사용 옵션이 나온다면 반드시 체크하는 것이 좋아요. Windows 환경에서는 WSL 2를 사용하는 것이 리눅스 커널을 직접 활용하기 때문에 훨씬 빠르고 안정적인 컨테이너 성능을 보장하기 때문이죠. 설치가 완료되면 Docker Desktop 앱을 실행하고, 터미널에서 docker compose version을 입력하여 정상 설치를 확인하면 돼요.
다만 주의할 점이 있어요. Docker Desktop은 가상화 기술을 사용하기 때문에 시스템 메모리를 상당히 많이 점유해요. 만약 노트북의 사양이 낮다면 컨테이너를 여러 개 띄웠을 때 전체적인 시스템 속도가 느려질 수 있다는 점을 고려해야 해요.
STEP 2. 리눅스 서버를 위한 Docker Compose Plugin 설치
Ubuntu나 Debian 같은 리눅스 서버를 운영 중이라면, Docker Desktop 대신 Docker Compose Plugin 방식을 사용하는 것이 정석이에요. 이는 도커 엔진의 명령어를 확장하는 방식(docker compose)으로 작동하며, 시스템 리소스를 거의 소모하지 않고도 매우 강력한 성능을 발휘해요.
Ubuntu 환경에서의 설치 시나리오는 다음과 같아요. 우선 기존의 구형 도커 패키지와 충돌하지 않도록 리포지토리를 먼저 업데이트해야 해요. sudo apt-get update를 실행한 뒤, 도커 공식 리포지토리를 등록하고 sudo apt-get install docker-compose-plugin 명령어를 통해 설치를 진행하세요. 이 방식의 가장 큰 장점은 패키지 관리자(apt)를 통해 보안 업데이트와 버전 관리가 자동화된다는 점이에요.
설치 후에는 반드시 docker compose(하이픈 없음) 명령어로 테스트해 보세요. 만약 예전 방식인 docker-compose(하이픈 있음) 명령어를 꼭 써야 하는 스크립트가 있다면, 별도의 심볼릭 링크 설정을 통해 호환성을 확보할 수 있어요. 서버 운영자라면 이 방식이 가장 예측 가능하고 안정적인 선택이 될 거예요.
STEP 3. 범용적인 Standalone 바이너리 수동 설치
만약 패키지 매니저를 사용할 수 없는 폐쇄망 환경이거나, 특정 버전의 도커 컴포즈가 반드시 필요한 특수한 상황이라면 Standalone 바이너리를 직접 내려받는 방법을 사용해야 해요. 이는 도커 엔진의 종류와 상관없이 실행 파일 하나만 있으면 어디서든 작동하는 방식이에요.
설치 단계는 조금 더 세밀한 주의가 필요해요. 먼저 GitHub의 Docker Compose 릴리스 페이지에서 본인의 시스템 아키텍처에 맞는 파일을 찾아야 해요. 예를 들어 일반적인 서버라면 linux-x86_64를, 최신 Mac이나 일부 ARM 서버라면 linux-aarch64를 선택해야 하죠. 파일을 내려받은 후에는 sudo curl -L ... -o /usr/local/bin/docker-compose 명령어를 통해 지정된 경로에 파일을 저장해야 해요.
바이너리를 수동으로 설치한 후에는 반드시
sudo chmod +x /usr/local/bin/docker-compose 명령어를 통해 실행 권한을 부여해야 해요. 권한 설정이 누락되면 파일을 내려받고도 실행할 수 없는 상황이 발생해요.이 방식은 설치 과정이 번거롭고 업데이트를 수동으로 챙겨야 한다는 단점이 있지만, 환경의 제약을 받지 않는다는 강력한 무기가 있어요. 특히 CI/CD 파이프라인 내부의 임시 실행 환경을 구성할 때 매우 유용하게 쓰여요.
STEP 4. 실제 운영 환경 구축 시나리오 예시
이해를 돕기 위해, 새로운 웹 애플리케이션 서버를 구축하는 가상의 시나리오를 구성해 볼게요. 여러분이 Ubuntu 22.04 서버를 새로 할당받았고, 여기에 Nginx와 PostgreSQL을 한꺼번에 띄워야 한다고 가정해 봅시다.
가장 권장되는 흐름은 다음과 같아요. 먼저 도커 엔진을 설치한 뒤, 앞서 설명한 CLI 플러그인 방식으로 컴포즈를 추가하는 것이죠. 설치가 끝나면 docker-compose.yml 파일을 작성하고 docker compose up -d 명령어를 입력합니다. 이때 플러그인 방식을 사용하면 도커 엔진의 업데이트와 함께 컴포즈 버전도 체계적으로 관리할 수 있어, 운영 중에 발생할 수 있는 버전 불일치 문제를 사전에 차단할 수 있어요. 만약 자동화 스크립트를 짠다면 apt-get install 한 줄로 모든 환경을 똑같이 복제할 수 있으니 운영 효율이 극대화될 거예요.
자주 하는 실수와 해결법
도커 컴포즈를 설치하고 실행하다 보면 예상치 못한 벽에 부딪히곤 해요. 많은 개발자가 공통적으로 겪는 실수들을 정리했으니, 문제가 생기면 바로 확인해 보세요.
- ❌ “command not found: docker-compose” 오류
왜 발생하는가: 도커 컴포즈가 설치되지 않았거나, 설치된 경로가 시스템의 PATH 환경 변수에 등록되지 않았기 때문이에요.
✅ 해결법: 설치 경로(예: /usr/local/bin)를 확인하고export PATH=$PATH:/usr/local/bin명령어를 통해 PATH에 추가하거나, 플러그인 방식인docker compose(하이픈 없이)를 사용해 보세요. - ❌ “permission denied” 권한 오류
왜 발생하는가: 도커 엔진이나 컴포즈 실행 파일에 대한 사용자 권한이 부족하기 때문이에요.
✅ 해결법: 명령어 앞에sudo를 붙여 실행하거나, 현재 사용자를docker그룹에 추가하여 sudo 없이 실행할 수 있도록 설정하세요. - ❌ 버전 불일치로 인한 설정 파일 오류
왜 발생하는가: 작성한docker-compose.yml의 문법은 최신 버전 기준인데, 설치된 컴포즈 버전이 너무 낮을 때 발생해요.
✅ 해결법:docker compose version으로 현재 버전을 확인하고, 최신 버전의 플러그인이나 바이너리로 업데이트하세요. - ❌ 아키텍처 미스매치(Wrong Architecture)
왜 발생하는가: ARM 기반의 Mac(M1/M2/M3) 환경에서 x86_64용 바이너리를 내려받았을 때 발생해요.
✅ 해결법: 자신의 CPU 아키텍처를 확인하고aarch64또는arm64용 파일을 다시 내려받으세요.
자주 묻는 질문
Q. Docker Desktop을 쓰면 리눅스 서버에서도 똑같이 쓸 수 있나요?
아니요, Docker Desktop은 Windows와 macOS를 위한 GUI 기반 도구예요. 리눅스 서버에서는 리소스를 아끼기 위해 Docker Desktop 대신 Docker Engine과 CLI 플러그인을 사용하는 것이 표준이에요.
Q. docker-compose(하이픈 있음)와 docker compose(하이픈 없음)의 차이는 무엇인가요?
하이픈이 있는 것은 과거 Python으로 만들어진 V1 방식이고, 하이픈이 없는 것은 최신 Go 언어 기반의 V2 방식이에요. 현재는 모두 V2를 지향하고 있으므로, 가급적 하이픈 없는 명령어를 사용하는 습관을 들이는 것이 좋아요.
Q. 설치 후에 명령어가 아예 안 먹혀요. 어떻게 하죠?
가장 먼저 설치 경로를 확인해 보세요. which docker-compose 또는 which docker 명령어를 입력했을 때 경로가 출력되지 않는다면 설치가 실패했거나 PATH 설정이 안 된 것이에요.
Q. 운영 서버에 Docker Desktop을 설치해도 되나요?
권장하지 않아요. Docker Desktop은 가상 머신을 하나 더 띄우는 방식이라 서버의 CPU와 메모리를 불필요하게 많이 사용하게 돼요. 서버에는 반드시 엔진과 플러그인만 설치하세요.
