[IT-방법] 도커 컴포즈 설치 실전 구축 가이드 - 운영 서버에 바로 적용하는 단계별 절차

도커 컴포즈 설치 실전 구축, 왜 지금 바로 시작해야 할까요

서버 터미널 앞에 앉아 복잡한 docker run 명령어를 하나씩 입력하다 보면 문득 이런 생각이 들 때가 있어요. “내가 지금 뭘 입력하고 있었지?” 포트 번호는 몇 번이었는지, 볼륨 경로는 어디로 지정했는지, 환경 변수는 또 무엇이었는지 기억하기란 여간 어려운 일이 아니에요. 특히 서비스 규모가 커져서 데이터베이스와 웹 서버를 함께 띄워야 하는 상황이 오면, 명령어 한 줄 한 줄을 직접 타이핑하는 방식은 마치 폭탄을 안고 달리는 기분이 들기도 해요.

단순한 실수 하나로 컨테이너가 엉뚱한 경로에 데이터를 쌓거나, 네트워크 설정이 꼬여 서비스가 먹통이 되는 경험은 1인 개발자에게 정말 큰 스트레스죠. 이런 혼란을 끝내고 서버 운영을 안정적인 궤도에 올리기 위해 반드시 필요한 도구가 바로 도커 컴포즈(Docker Compose)예요. 도커 컴포즈는 여러 개의 컨테이너를 하나의 설정 파일로 정의하고, 명령어 한 번으로 전체 서비스를 실행하거나 멈출 수 있게 도와주는 강력한 도구랍니다.

이제는 명령어를 외워서 입력하는 시대가 아니에요. 어떻게 하면 내가 구축한 환경을 코드로 기록하고, 언제 어디서든 똑같이 재현할 수 있을지를 고민해야 하는 시점이죠. 이번 가이드를 통해 도커 컴포즈를 단순히 설치하는 수준을 넘어, 실제 운영 서버에서 바로 사용할 수 있는 수준의 구축 프로세스를 익히게 될 거예요.

💡 알아두기
도커 컴포즈는 도커 엔진 위에서 동작하는 도구예요. 즉, 도커 컴포즈를 설치하기 전에 반드시 도커 엔진이 먼저 깔려 있어야 한다는 점을 기억하세요!

이번 글에서는 다음 내용들을 아주 구체적으로 다룰 예정이에요.

설치 전 점검해야 할 서버 사양과 환경 설정
최신 방식인 도커 컴포즈 플러그인 설치 절차
실무에서 바로 쓰는 디렉터리 구조 설계법
복잡한 서비스를 정의하는 docker-compose.yml 작성법
운영 중 마주치는 흔한 실수와 해결 방법

설치 전 반드시 체크해야 할 운영 환경과 필수 조건

무턱대고 설치 명령어부터 입력하기보다는, 현재 내 서버가 도커 컴포즈를 받아들일 준비가 되었는지 확인하는 과정이 먼저예요. 준비 없이 진행했다가는 의존성 오류로 인해 시간을 허비하거나, 최악의 경우 기존에 돌고 있던 컨테이너에 영향을 줄 수도 있거든요.

서버 사양 및 운영체제 확인하기

도커 컴포즈 자체는 매우 가벼운 도구라서 사양을 많이 타지는 않아요. 하지만 도커 컴포즈로 띄울 실제 서비스의 무게를 고려해야 해요. 최소한 Ubuntu 20.04 LTS 이상의 환경을 권장하며, 메모리는 최소 1GB 이상, 안정적인 서비스를 위해서는 2GB 이상을 확보하는 것이 좋아요. 특히 스왑(Swap) 메모리를 설정해두면 갑작스러운 트래픽 증가로 메모리가 부족할 때 서버가 완전히 멈추는 것을 방지할 수 있어요.

도커 컴포즈 설치 방식 선택하기

설치 방법은 크게 두 가지로 나뉘어요. 과거에는 별도의 바이너리 파일을 다운로드해서 설치하는 방식을 많이 썼지만, 지금은 도커의 공식 플러그인 형태로 설치하는 것이 표준이에요. 어떤 방식을 선택하느냐에 따라 명령어가 조금 달라지니 아래 표를 보고 본인에게 맞는 방식을 결정하세요.

구분	도커 컴포즈 플러그인 (권장)	독립형 바이너리 (구형)
사용 명령어	`docker compose`	`docker-compose`
설치 편의성	패키지 관리자로 자동 업데이트 가능	수동으로 파일을 내려받아 관리 필요
호환성	최신 도커 엔진과 최적화됨	버전 불일치 가능성 존재
추천 대상	대부분의 신규 구축 사용자	기존 레거시 환경 유지보수자

체크리스트 준비하기

설치를 시작하기 전에 다음 항목들을 미리 준비해두면 진행 속도가 훨씬 빨라져요.

서버 접속 권한: root 권한 또는 sudo 권한이 있는 계정
네트워크 상태: 외부 저장소(GitHub, Docker Hub 등)에 접속 가능한 인터넷 환경
기존 도커 설치 여부: docker --version 명령어로 설치 여부를 미리 확인해보세요.

⚠️ 주의
만약 기존에 아주 오래된 버전의 도커를 사용 중이라면, 컴포즈 설치 과정에서 충돌이 날 수 있어요. 이럴 때는 기존 도커를 완전히 삭제하고 최신 버전으로 재설치하는 것을 추천해요.

실전! 도커 컴포즈 설치부터 서비스 운영까지 단계별 가이드

이제 본격적으로 도커 컴포즈를 설치하고, 실제 서비스를 띄울 수 있는 환경을 만들어볼게요. 가장 대중적인 Ubuntu 환경을 기준으로 설명할 테니, 다른 운영체제를 사용하신다면 비슷한 흐름으로 따라오시면 돼요.

STEP 1. 시스템 업데이트 및 필수 패키지 설치

먼저 서버의 패키지 목록을 최신 상태로 만들고, 설치 과정에서 필요한 도구들을 미리 깔아둬야 해요. 터미널에 아래 명령어를 순서대로 입력해 보세요.

sudo apt-get update sudo apt-get install ca-certificates curl gnupg

이 과정은 보안 통신을 위한 인증서와 저장소 주소를 안전하게 가져오기 위한 기초 공사예요. 이 단계를 건너뛰면 나중에 저장소를 추가할 때 오류가 발생할 확률이 높으니 꼭 거쳐 가야 해요.

STEP 2. 도커 공식 저장소 등록 및 컴포즈 플러그인 설치

도커 컴포즈는 도커 공식 저장소에서 관리하므로, 내 서버가 도커의 공식 저장소를 바라보게 설정해야 해요. 이렇게 해야 나중에 apt upgrade 명령만으로도 도커와 컴포즈를 한꺼번에 최신 버전으로 유지할 수 있거든요.

먼저 도커의 GPG 키를 추가합니다.
sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg

그다음 저장소를 시스템에 등록해요.
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

이제 모든 준비가 끝났으니, 드디어 컴포즈 플러그인을 설치합니다.
sudo apt-get update sudo apt-get install docker-compose-plugin

설치가 완료되었다면 docker compose version을 입력해서 버전 정보가 정상적으로 출력되는지 꼭 확인하세요. 이 한 줄이 성공했다면, 여러분은 이제 컨테이너 오케스트레이션의 세계로 들어온 거예요.

STEP 3. 운영 효율을 높이는 디렉터리 구조 설계

많은 초보 개발자들이 하는 실수 중 하나가 모든 파일을 루트 디렉터리나 홈 디렉터리에 뒤섞어 놓는 거예요. 그렇게 되면 나중에 어떤 데이터가 어디에 저장되어 있는지 찾기가 불가능해지죠. 실무에서는 다음과 같은 구조를 권장해요.

/home/user/my-service/ (프로젝트 루트)
- docker-compose.yml (전체 서비스 정의 파일)
- .env (환경 변수 관리 파일)
- nginx/ (웹 서버 설정 및 파일)
- db_data/ (데이터베이스 영구 저장 데이터 – Git 제외 필수)
- app/ (애플리케이션 소스 코드)

이렇게 구조를 나누어 놓으면, 나중에 서버를 이전하거나 백업할 때 my-service 폴더 하나만 통째로 옮기면 되니까 정말 편리해요.

STEP 4. 서비스 정의와 의존관계 구성 실전

이제 핵심인 docker-compose.yml 파일을 작성해볼게요. 간단하지만 강력한 Nginx와 MariaDB를 조합한 웹 서버 환경을 예로 들어볼게요. 이 파일을 프로젝트 루트에 만드세요.

version: '3.8' services: db: image: mariadb:10.6 restart: always environment: MYSQL_ROOT_PASSWORD: mysecretpassword MYSQL_DATABASE: myapp volumes: - ./db_data:/var/lib/mysql networks: - app-network


  web:
    image: nginx:latest
    ports:
      - "80:80"
    depends_on:
      - db
    networks:
      - app-network

networks: app-network: driver: bridge

이 설정 파일의 의미를 꼼꼼히 살펴볼까요?
첫째, depends_on은 매우 중요해요. 웹 서버가 실행되기 전에 데이터베이스가 먼저 준비되어야 한다는 의존성을 명시하는 것이죠.
둘째, volumes 설정을 통해 컨테이너가 삭제되어도 데이터베이스의 데이터가 사라지지 않도록 호스트의 ./db_data 폴더에 연결해두었어요.
셋째, networks를 통해 컨테이너들끼리만 통신할 수 있는 독립된 가상 네트워크를 만들어 보안을 강화했어요.

STEP 5. 서비스 실행 및 초기 설정 확인

파일 작성이 끝났다면 이제 마법을 부릴 시간이에요. 터미널에서 해당 디렉터리로 이동한 뒤 아래 명령어를 입력하세요.

docker compose up -d

-d 옵션은 detached mode로, 컨테이너를 백그라운드에서 실행하라는 뜻이에요. 이 옵션 없이 실행하면 터미널을 닫는 순간 서비스도 멈춰버리니 주의하세요! 실행 후에는 docker compose ps 명령어를 통해 컨테이너들이 ‘Up’ 상태인지 확인해보세요. 모든 것이 정상이라면 브라우저에서 서버 IP로 접속했을 때 Nginx의 환영 페이지가 보일 거예요.

💡 알아두기
설정 파일을 수정했다면 다시 docker compose up -d를 입력하세요. 도커 컴포즈는 변경된 부분만 감지해서 필요한 컨테이너만 똑똑하게 다시 생성해준답니다.

자주 하는 실수와 해결법

실전 구축 과정에서는 예상치 못한 오류들이 튀어나오기 마련이에요. 당황하지 말고 아래의 대표적인 실수 사례들을 참고해보세요.

❌ YAML 파일의 들여쓰기 오류
왜 발생할까요? YAML은 들여쓰기(Space)에 매우 민감한 형식이에요. 탭(Tab)을 섞어 쓰거나 칸 수가 어긋나면 문법 오류가 발생해요.
✅ 해결법: 반드시 스페이스(Space)를 사용하고, VS Code 같은 에디터의 ‘YAML 확장 프로그램’을 사용해 시각적으로 확인하세요.
❌ 포트 충돌 (Port Conflict)
왜 발생할까요? 이미 서버에서 사용 중인 포트(예: 80번 포트)를 다른 컨테이너가 또 점유하려고 할 때 발생해요.
✅ 해결법: netstat -tnlp 명령어로 현재 사용 중인 포트를 확인하거나, docker-compose.yml에서 왼쪽 포트 번호를 변경하세요. (예: “8080:80”)
❌ 권한 거부 (Permission Denied)
왜 발생할까요? 도커 명령어를 실행할 권한이 없는 일반 사용자 계정으로 시도했기 때문이에요.
✅ 해결법: 명령어 앞에 sudo를 붙이거나, 현재 사용자를 docker 그룹에 추가하여 권한을 부여하세요.
❌ 볼륨 경로 인식 불가
왜 발생할까요? 상대 경로(./)를 잘못 지정했거나, 호스트 운영체제의 권한 문제로 컨테이너가 파일을 쓰지 못하는 경우예요.
✅ 해결법: 가급적 절대 경로를 사용해보고, 데이터 폴더의 쓰기 권한을 확인하세요.
❌ 네트워크 연결 실패
왜 발생할까요? 컨테이너끼리 통신할 때 서비스 이름을 사용하지 않고 IP를 직접 사용하려 했기 때문이에요.
✅ 해결법: 도커 컴포즈 내부에서는 IP 대신 docker-compose.yml에 정의한 서비스 이름(예: db, web)을 호스트 이름처럼 사용하세요.

자주 묻는 질문

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

과거에는 별도의 프로그램이었던 docker-compose(하이픈 포함)를 썼지만, 최신 방식은 도커 엔진의 플러그인 형태인 docker compose(공백 사용)를 쓰는 것이 표준이에요. 최신 환경이라면 공백을 사용하는 방식을 강력히 추천해요.

Q. 설정 파일을 바꿨는데 적용이 안 되는 것 같아요. 어떻게 하죠?

단순히 실행 중인 컨테이너를 끄는 게 아니라, docker compose up -d를 다시 입력해야 해요. 그러면 도커 컴포즈가 설정 파일의 변경 사항을 감지하고, 변경된 컨테이너만 골라서 새로 만들어준답니다.

Q. 운영 중인 컨테이너를 안전하게 멈추려면 어떻게 하나요?

docker compose stop은 컨테이너를 잠시 멈추는 것이고, docker compose down은 컨테이너와 네트워크를 완전히 제거하는 것이에요. 데이터를 안전하게 보관하려면 반드시 volumes 설정이 되어 있어야 한다는 점을 잊지 마세요!

Q. 메모리가 부족해서 컨테이너가 자꾸 죽어요.

YAML 파일 내에 deploy: resources: limits: 설정을 추가하여 각 서비스가 사용할 수 있는 메모리의 최대치를 제한해보세요. 서버 전체가 다운되는 것을 막을 수 있어요.

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

도커 컴포즈 설치 실전 구축 과정을 모두 마쳤습니다. 처음에는 명령어가 낯설고 설정 파일의 구조가 복잡해 보일 수 있지만, 한 번 제대로 구축해두면 서버 관리의 차원이 달라지는 것을 경험하실 거예요. 이제 여러분은 더 이상 명령어를 외우지 않아도 되고, 언제든 코드를 통해 서버 환경을 복구할 수 있는 능력을 갖추게 되었습니다.

✅ 핵심 요약

도커 엔진이 설치된 상태에서 도커 컴포즈 플러그인 방식으로 설치하세요.
프로젝트 디렉터리를 체계적으로 나누어 관리 효율성을 높이세요.
데이터를 지키기 위해 볼륨(Volumes) 설정은 선택이 아닌 필수예요.
YAML 작성 시 들여쓰기 규칙을 엄격히 준수하세요.
서비스 간 통신은 IP가 아닌 서비스 이름을 사용하세요.

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

오늘 할 일: 현재 사용 중인 서버에 도커와 컴포즈가 설치되어 있는지 확인하고, 위 가이드를 따라 최신 버전으로 업데이트하기
이번 주 할 일: 테스트용 프로젝트 폴더를 만들고 Nginx와 DB를 연동하는 docker-compose.yml을 직접 작성해 실행해보기
실행 직전 할 일: 작성한 설정 파일을 Git 저장소에 올려서 버전 관리를 시작하기

구축 절차를 문서로 꼼꼼히 남겨 두면, 나중에 서버를 이전하거나 새로운 환경을 구축할 때 훨씬 쉬워집니다. 여러분의 안정적인 서버 운영을 응원할게요!

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

[IT-방법] 도커 컴포즈 설치 실전 구축 가이드 – 운영 서버에 바로 적용하는 단계별 절차