Docker Compose 웹개발 환경 구축 실제 사용 가이드

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

로컬 환경이 매번 꼬일 때 Docker Compose를 꺼낸 이유

제 노트북에서만 되던 웹개발 프로젝트의 반복 문제

웹개발을 하다 보면 코드보다 환경 설정에 시간을 더 쓰는 날이 있습니다. Node 버전은 맞는데 PostgreSQL 포트가 충돌하고, Redis는 켜져 있다고 생각했는데 다른 프로젝트 컨테이너가 잡고 있고, 팀원에게는 같은 명령어가 동작하지 않는 상황을 여러 번 겪었습니다.

저는 2026년 기준으로 개인 프로젝트와 작은 팀 프로젝트에서 Docker Compose 기반 개발 환경을 기본값처럼 쓰고 있습니다. 처음에는 Dockerfile과 compose.yaml이 부담스러웠지만, 한 번 틀을 잡아두니 새 노트북이나 새 팀원 온보딩에서 체감 차이가 컸습니다.

특히 백엔드 API, 프론트엔드, 데이터베이스를 함께 다루는 프로젝트라면 Docker Compose는 단순한 배포 도구가 아니라 반복 가능한 코딩 환경을 만드는 개발 습관에 가깝습니다. 코딩과 프로그래밍의 기본 개념이 궁금하다면 네이버 지식백과의 코딩 설명처럼 용어를 먼저 정리해두는 것도 도움이 됩니다.

• 좋았던 점: 팀원마다 다른 OS를 쓰더라도 실행 명령을 거의 동일하게 맞출 수 있었습니다.
• 아쉬웠던 점: 처음 설정 파일을 잘못 만들면 오히려 디버깅 범위가 넓어집니다.
• 추천 대상: DB, 캐시, 백엔드 서버를 함께 띄우는 웹개발 입문자와 주니어 개발자입니다.

제가 체감한 가장 큰 장점은 설치 문서가 짧아진다는 점입니다. npm install, DB 설치, 계정 생성, 포트 설정을 길게 설명하는 대신 docker compose up 한 줄로 시작점을 맞출 수 있었습니다.

실제로 써보니 편했던 기본 구성과 파일 구조

처음부터 거창하게 만들 필요는 없었습니다

처음 Docker Compose를 적용할 때는 모든 것을 컨테이너로 옮기려다 실패했습니다. 프론트엔드 핫 리로드, 백엔드 디버거, 데이터베이스 볼륨까지 한 번에 잡으려니 문제가 생겼을 때 원인을 찾기 어려웠습니다.

지금은 가장 단순한 구성부터 시작합니다. 예를 들어 React나 Next.js 같은 프론트엔드는 로컬에서 실행하고, PostgreSQL과 Redis만 Compose로 띄우는 방식입니다. 이후 백엔드 API까지 컨테이너화할 필요가 생기면 단계적으로 추가합니다.

프로그래밍은 결국 문제를 작은 단위로 나누는 과정입니다. 용어 관점에서 더 넓게 보고 싶다면 프로그래밍의 기본 정의를 함께 확인해보셔도 좋습니다. Docker Compose도 마찬가지로 한 번에 완벽한 환경을 만드는 도구라기보다, 반복되는 실행 조건을 코드로 나누어 기록하는 방식에 가깝습니다.

제가 가장 자주 쓰는 구성

1. app: Node.js, Spring Boot, Django 같은 실제 애플리케이션 서버를 실행합니다.
2. db: PostgreSQL 또는 MySQL을 올리고 볼륨을 연결해 데이터를 유지합니다.
3. cache: Redis를 붙여 로그인 세션, 큐, 캐시 테스트를 합니다.
4. admin: 필요할 때만 Adminer나 pgAdmin 같은 관리 도구를 추가합니다.

이 구성의 장점은 개발자가 현재 어떤 서비스가 필요한지 눈으로 확인하기 쉽다는 점입니다. compose.yaml 하나에 서비스 이름, 포트, 환경 변수, 볼륨이 모여 있으니 README를 읽기 전에 구조가 먼저 보입니다.

• 파일명: 2026년 기준으로는 docker-compose.yml보다 compose.yaml을 쓰는 팀도 많습니다.
• 환경 변수: .env 파일을 분리해 비밀번호와 포트 값을 관리하는 편이 안전합니다.
• 볼륨: DB 데이터는 named volume을 사용해야 컨테이너를 내려도 데이터가 쉽게 사라지지 않습니다.

장점보다 먼저 알아야 할 단점과 실패 사례

느려지는 순간은 분명히 있습니다

Docker Compose가 만능은 아닙니다. 제 경험상 Mac이나 Windows에서 파일 공유가 많은 프론트엔드 프로젝트를 컨테이너 안에서 실행하면 핫 리로드가 로컬 실행보다 느리게 느껴질 때가 있었습니다. 특히 node_modules를 컨테이너와 호스트가 어설프게 공유하면 설치 속도와 타입 체크 속도 모두 답답해질 수 있습니다.

그래서 저는 프론트엔드까지 무조건 컨테이너로 넣지 않습니다. 팀원 OS 차이 때문에 반드시 필요한 경우가 아니라면 프론트엔드는 로컬 Node로 실행하고, DB와 Redis처럼 설치가 번거로운 의존성만 Compose로 관리합니다. 이 방식이 실제 웹개발 작업에서는 더 빠르고 덜 피곤했습니다.

환경 파일 관리가 허술하면 보안 문제가 됩니다

또 하나의 실수는 .env 파일을 아무 생각 없이 Git에 올리는 것입니다. 로컬 개발용 비밀번호라 해도 습관이 굳어지면 운영 환경에서도 같은 실수를 할 가능성이 큽니다. 저는 .env.example만 저장소에 올리고 실제 .env는 gitignore에 넣는 규칙을 팀 템플릿에 박아두었습니다.

• 실패 사례 1: DB 볼륨 이름을 프로젝트마다 같게 써서 다른 프로젝트 데이터와 헷갈린 적이 있습니다.
• 실패 사례 2: 포트 5432를 모든 프로젝트가 쓰게 해두어 동시에 실행할 때 충돌이 났습니다.
• 실패 사례 3: 컨테이너 내부 시간대 설정을 놓쳐 로그 시간이 한국 시간과 다르게 찍혔습니다.
• 해결 팁: 프로젝트명 접두사를 붙인 볼륨, 명시적인 외부 포트, TZ=Asia/Seoul 환경 변수를 기본값으로 둡니다.

Docker Compose를 잘 쓰는 핵심은 모든 것을 컨테이너로 넣는 것이 아니라, 팀의 반복 작업 중 가장 자주 깨지는 부분부터 컨테이너로 고정하는 것입니다.

초보자에게 추천하는 단계별 적용 방법

1단계: 데이터베이스만 먼저 컨테이너로 분리

코딩 입문자에게 가장 먼저 추천하는 방식은 데이터베이스만 Docker Compose로 띄우는 것입니다. PostgreSQL이나 MySQL은 설치 과정에서 계정, 포트, 서비스 실행 여부가 꼬이기 쉽습니다. 컨테이너로 분리하면 삭제와 재생성이 쉬워 실습 부담이 줄어듭니다.

예를 들어 백엔드 튜토리얼을 따라가다 DB 연결 에러가 나면 초보자는 코드가 틀린 것인지 DB가 꺼진 것인지 구분하기 어렵습니다. compose.yaml로 DB 실행 조건을 고정하면 문제 범위가 줄어들고, 개발자는 실제 로직과 SQL 학습에 더 집중할 수 있습니다.

2단계: API 서버와 테스트 환경 추가

두 번째 단계에서는 API 서버를 컨테이너에 넣어봅니다. 이때 중요한 것은 운영 배포용 이미지와 개발용 이미지를 구분하는 것입니다. 개발용 컨테이너는 볼륨 마운트와 핫 리로드가 중요하고, 운영용 이미지는 용량과 실행 안정성이 중요합니다.

1. DB 컨테이너부터 시작: 가장 효과가 크고 설정 범위가 작습니다.
2. Redis 추가: 로그인, 캐시, 큐 기능을 실습할 때 유용합니다.
3. API 서버 추가: 팀원 온보딩이 잦거나 서버 런타임 버전 차이가 클 때 적용합니다.
4. 테스트 DB 분리: 자동화 테스트를 운영 데이터와 분리해 안정적으로 돌립니다.

이 순서대로 적용하면 Docker 학습이 부담스럽지 않습니다. 개발 환경을 코드화한다는 개념이 익숙해지고 나면, 배포 파이프라인이나 CI에서도 비슷한 사고방식을 이어갈 수 있습니다. 처음부터 완성형 템플릿을 복사하기보다 작은 성공 경험을 쌓는 편이 훨씬 오래갑니다.

실제 프로젝트에서 쓴 체크리스트와 비교표

Compose 적용 전 확인한 항목

저는 새 프로젝트에 Docker Compose를 붙이기 전에 체크리스트를 먼저 봅니다. 이 프로젝트가 정말 컨테이너가 필요한 구조인지, 아니면 단순한 정적 페이지나 프론트엔드 실습이라 로컬 실행만으로 충분한지 판단하기 위해서입니다.

무조건 도입하면 관리 파일만 늘어납니다. 반대로 데이터베이스, 캐시, 메시지 큐, 검색 엔진처럼 설치형 의존성이 많다면 Compose는 유지보수 비용을 줄이는 쪽으로 작동합니다. 특히 여러 명이 같은 튜토리얼이나 사내 과제를 진행할 때 차이가 큽니다.

• 의존성 개수: DB 외에 Redis, Elasticsearch, MinIO 등이 있다면 도입 가치가 큽니다.
• 팀원 수: 혼자보다 팀원이 많을수록 환경 통일 효과가 커집니다.
• 운영 유사성: 로컬과 배포 환경의 차이를 줄이고 싶다면 유리합니다.
• 학습 비용: Docker 명령어와 로그 확인법을 익힐 시간이 필요합니다.

로컬 설치와 Docker Compose 비교

제가 느낀 현실적인 기준은 간단합니다. 단일 프론트엔드 프로젝트라면 로컬 실행이 편하고, 서버와 DB가 붙는 순간부터는 Compose가 편합니다. 웹개발 프로젝트가 커질수록 실행 방법을 문서로만 설명하는 것보다 설정 파일로 남기는 쪽이 실수를 줄여줍니다.

이것만은 꼭 기억하세요: 명령어와 운영 팁

자주 쓰는 명령어는 몇 개면 충분합니다

Docker Compose를 잘 쓰기 위해 모든 명령어를 외울 필요는 없습니다. 실제 작업에서 제가 자주 쓰는 명령어는 docker compose up -d, docker compose logs -f, docker compose down, docker compose ps 정도입니다. 이 네 가지만 익숙해져도 대부분의 로컬 개발 상황은 처리할 수 있습니다.

문제가 생겼을 때는 컨테이너를 지우기 전에 로그부터 봐야 합니다. 초보자일수록 에러가 나면 바로 down -v로 볼륨까지 삭제하는데, 그러면 원인 분석에 필요한 데이터도 함께 사라집니다. 먼저 logs로 에러 메시지를 확인하고, 그다음 설정 파일과 환경 변수를 비교하는 습관이 좋습니다.

팀 프로젝트에 넣으면 좋은 운영 규칙

• README 첫 줄에 실행 명령 작성: 새 팀원이 가장 먼저 볼 수 있게 합니다.
• .env.example 제공: 필요한 환경 변수 이름과 예시 값을 명확히 남깁니다.
• 포트 규칙 통일: 3000, 8080, 5432처럼 자주 겹치는 포트는 프로젝트별로 조정합니다.
• 헬스체크 추가: DB가 완전히 뜨기 전에 API가 먼저 실행되어 실패하는 문제를 줄입니다.
• 개발용과 운영용 분리: compose.override.yaml이나 별도 파일로 목적을 나눕니다.

마지막으로 비용도 현실적으로 봐야 합니다. Docker 자체 학습은 무료 자료가 많고 개인 학습 환경은 부담 없이 시작할 수 있지만, 회사에서 Docker Desktop을 사용할 때는 조직 규모와 라이선스 정책을 반드시 확인해야 합니다. 2026년에도 개발 도구의 가격과 약관은 바뀔 수 있으므로 팀 표준으로 정하기 전 공식 안내를 확인하는 편이 안전합니다.

웹개발을 계속하다 보면 프레임워크 선택보다 실행 환경 관리가 생산성을 더 크게 좌우하는 순간이 옵니다. Docker Compose는 화려한 도구는 아니지만, 프로젝트를 다시 열었을 때 같은 상태로 시작하게 해주는 든든한 기반입니다. 다음 프로젝트에서 DB 설치 문서가 길어지고 있다면, 그 지점이 Compose를 도입해볼 좋은 신호입니다.