Deployment 완벽 마스터
Deployment의 핵심 개념과 실전 활용법
학습 항목
이미지 로딩 중...
Docker 컨테이너 기초 완벽 가이드
Docker 컨테이너의 기본 개념부터 실전 활용까지 초급 개발자를 위한 완벽 가이드입니다. 컨테이너 생성, 실행, 관리의 핵심 개념들을 실무 예제와 함께 배워보세요. 개발 환경 구성부터 배포까지 실전에서 바로 사용할 수 있는 Docker 기초를 다룹니다.
목차
- Docker 컨테이너란 무엇인가 - 가상화의 새로운 패러다임
- Docker 이미지 이해하기 - 컨테이너의 설계도
- Dockerfile 작성하기 - 나만의 이미지 만들기
- Docker 볼륨과 데이터 관리 - 컨테이너의 영속성 확보
- Docker 네트워킹 - 컨테이너 간 통신
- Docker Compose 입문 - 멀티 컨테이너 애플리케이션 관리
- 컨테이너 환경변수와 설정 관리 - 보안과 유연성의 핵심
- 컨테이너 로그 관리와 디버깅 - 문제 해결의 시작점
- Docker 이미지 최적화 - 크기와 빌드 시간 줄이기
- 컨테이너 헬스체크와 재시작 정책 - 안정성과 자동 복구
1. Docker 컨테이너란 무엇인가 - 가상화의 새로운 패러다임
시작하며
여러분이 새로운 프로젝트를 시작할 때마다 "내 컴퓨터에서는 되는데?"라는 말을 들어본 적 있나요? 개발 환경에서는 완벽하게 작동하던 애플리케이션이 배포 서버에서는 오류를 내는 상황, 팀원마다 다른 환경 설정 때문에 프로젝트 세팅에 하루를 소비하는 경험 말이죠.
이런 문제는 실제 개발 현장에서 매일 발생합니다. 운영체제의 차이, 라이브러리 버전 불일치, 환경변수 설정 누락 등 수많은 변수들이 개발 생산성을 떨어뜨립니다.
특히 팀 프로젝트에서는 이런 환경 차이 때문에 협업이 어려워지고, 배포 과정에서 예상치 못한 문제들이 발생합니다. 바로 이럴 때 필요한 것이 Docker 컨테이너입니다.
Docker는 애플리케이션과 그 실행 환경을 하나의 패키지로 묶어서 어디서든 동일하게 실행할 수 있게 해줍니다. "한 번 만들면 어디서나 실행된다"는 Docker의 철학이 여러분의 개발 워크플로우를 완전히 바꿔놓을 것입니다.
개요
간단히 말해서, Docker 컨테이너는 애플리케이션과 그 실행에 필요한 모든 것을 격리된 환경에 담아 실행하는 경량 가상화 기술입니다. 전통적인 가상머신이 운영체제 전체를 가상화하는 것과 달리, Docker 컨테이너는 호스트 OS의 커널을 공유하면서 프로세스를 격리합니다.
이로 인해 컨테이너는 몇 초 만에 시작되고, 시스템 리소스를 훨씬 효율적으로 사용합니다. 예를 들어, 마이크로서비스 아키텍처에서 수십 개의 서비스를 동시에 실행해야 할 때, 가상머신으로는 리소스 부족 문제가 발생하지만 컨테이너는 가볍게 처리할 수 있습니다.
기존에는 개발 환경을 맞추기 위해 설치 문서를 따라 하나씩 설정했다면, 이제는 Docker 컨테이너 하나만 실행하면 즉시 동일한 환경을 얻을 수 있습니다. Docker 컨테이너의 핵심 특징은 첫째, 이식성(Portability)입니다.
개발 PC, 테스트 서버, 운영 서버 어디서든 동일하게 실행됩니다. 둘째, 격리성(Isolation)입니다.
각 컨테이너는 독립된 파일시스템과 네트워크를 가지므로 서로 영향을 주지 않습니다. 셋째, 경량성(Lightweight)입니다.
필요한 것만 포함하여 빠르게 시작하고 적은 리소스를 사용합니다. 이러한 특징들이 현대적인 DevOps 환경에서 Docker를 필수 도구로 만들었습니다.
코드 예제
# Docker 컨테이너 기본 명령어들
# 컨테이너 실행 - nginx 웹서버를 백그라운드로 실행
docker run -d --name my-nginx -p 8080:80 nginx
# 실행 중인 컨테이너 목록 확인
docker ps
# 컨테이너 내부에서 명령 실행 - 쉘 접속
docker exec -it my-nginx /bin/bash
# 컨테이너 로그 확인 - 실시간으로 모니터링
docker logs -f my-nginx
# 컨테이너 중지 및 삭제
docker stop my-nginx
docker rm my-nginx
설명
이것이 하는 일: Docker 컨테이너는 애플리케이션 실행에 필요한 코드, 런타임, 라이브러리, 설정 파일 등을 모두 포함한 표준화된 실행 단위를 만들어 일관된 환경을 보장합니다. 첫 번째로, docker run 명령은 컨테이너를 생성하고 실행합니다.
-d 플래그는 백그라운드 모드로 실행하고, --name으로 컨테이너에 이름을 부여하며, -p 8080:80은 호스트의 8080 포트를 컨테이너의 80 포트로 연결합니다. 이렇게 하는 이유는 컨테이너가 격리된 환경이므로 명시적으로 포트를 연결해야 외부에서 접근할 수 있기 때문입니다.
nginx는 사용할 이미지 이름으로, Docker Hub에서 자동으로 다운로드됩니다. 그 다음으로, docker ps로 현재 실행 중인 컨테이너들을 확인할 수 있습니다.
이 명령은 컨테이너 ID, 이미지, 생성 시간, 상태, 포트 매핑 등의 정보를 보여줍니다. docker exec -it는 실행 중인 컨테이너 내부에 접속하여 명령을 실행할 수 있게 해줍니다.
-it 플래그는 인터랙티브 터미널 모드를 의미하며, 이를 통해 컨테이너 내부를 직접 탐색하거나 디버깅할 수 있습니다. 마지막으로, docker logs는 컨테이너의 표준 출력과 에러를 확인할 수 있습니다.
-f 플래그는 실시간으로 로그를 추적하여, 애플리케이션의 동작을 모니터링하고 문제를 빠르게 파악할 수 있습니다. docker stop과 docker rm은 컨테이너를 정리하는 명령으로, 리소스 관리를 위해 사용하지 않는 컨테이너는 삭제하는 것이 좋습니다.
여러분이 이 코드를 사용하면 몇 초 만에 완전한 웹서버 환경을 구축하고, 필요 없을 때는 즉시 제거할 수 있습니다. 개발 중에 여러 버전의 데이터베이스를 테스트하거나, 다양한 설정을 실험해볼 때 시스템을 오염시키지 않고 깨끗한 환경에서 작업할 수 있습니다.
또한 팀원 모두가 동일한 명령어로 같은 환경을 구축하므로 협업이 훨씬 수월해집니다.
실전 팁
💡 docker run --rm 플래그를 사용하면 컨테이너 종료 시 자동으로 삭제되어 시스템을 깔끔하게 유지할 수 있습니다. 일회성 테스트나 실험용 컨테이너에 유용합니다.
💡 컨테이너 이름을 명확하게 지정하지 않으면 Docker가 임의의 이름을 부여합니다. 관리하기 쉽도록 항상 의미 있는 이름을 붙이는 습관을 들이세요.
💡 docker ps -a를 사용하면 중지된 컨테이너까지 모두 볼 수 있습니다. 주기적으로 확인하고 docker container prune으로 사용하지 않는 컨테이너를 정리하세요.
💡 포트 충돌을 피하기 위해 호스트 포트는 겹치지 않게 관리하고, 개발 환경에서는 8080, 8081과 같이 순차적으로 할당하는 규칙을 정하면 좋습니다.
💡 컨테이너 내부 쉘 접속 시 /bin/bash가 없는 경우 /bin/sh를 사용하세요. Alpine Linux 기반 이미지는 경량화를 위해 bash 대신 sh를 사용합니다.
2. Docker 이미지 이해하기 - 컨테이너의 설계도
시작하며
여러분이 애플리케이션을 배포할 때마다 서버에 Node.js를 설치하고, 의존성 패키지를 다운로드하고, 환경 설정을 복사하는 과정을 반복하고 계신가요? 서버가 10대, 100대로 늘어나면 이 과정은 악몽이 됩니다.
더 큰 문제는 각 서버마다 미묘하게 다른 환경이 만들어져 버그의 온상이 된다는 점입니다. 이런 배포 지옥에서 벗어나려면 표준화된 패키징 방식이 필요합니다.
애플리케이션 코드, 런타임, 라이브러리, 설정을 하나의 불변(Immutable) 패키지로 만들어 언제 어디서든 동일하게 배포할 수 있어야 합니다. Docker 이미지가 바로 그 해결책입니다.
이미지는 컨테이너를 만들기 위한 템플릿으로, 한 번 만들면 무한히 재사용할 수 있는 애플리케이션의 스냅샷입니다. 이미지만 있으면 몇 초 만에 수백 개의 동일한 컨테이너를 생성할 수 있습니다.
개요
간단히 말해서, Docker 이미지는 컨테이너를 생성하기 위한 읽기 전용 템플릿으로, 애플리케이션 실행에 필요한 모든 파일과 설정이 계층적으로 쌓여 있는 구조입니다. 이미지는 레이어(Layer) 시스템을 사용합니다.
각 레이어는 이전 레이어의 변경사항만 기록하며, 여러 이미지가 공통 레이어를 공유할 수 있어 저장 공간과 전송 시간을 크게 절약합니다. 예를 들어, Ubuntu 기반 이미지 10개를 사용하더라도 Ubuntu 베이스 레이어는 한 번만 다운로드되고, 나머지는 차이점만 받으면 됩니다.
이러한 효율성 덕분에 CI/CD 파이프라인에서 빠른 빌드와 배포가 가능합니다. 기존에는 애플리케이션 설치 스크립트를 작성하고 서버마다 실행했다면, 이제는 이미지를 빌드하여 레지스트리에 푸시하고 어디서든 풀(Pull)해서 사용할 수 있습니다.
Docker 이미지의 핵심 특징은 첫째, 불변성(Immutability)입니다. 한 번 생성된 이미지는 변경되지 않아 예측 가능한 배포를 보장합니다.
둘째, 버전 관리가 가능합니다. 태그를 통해 여러 버전을 관리하고 필요시 이전 버전으로 롤백할 수 있습니다.
셋째, 공유와 재사용이 쉽습니다. Docker Hub 같은 레지스트리를 통해 전 세계 개발자들과 이미지를 공유할 수 있습니다.
이러한 특징들이 Docker를 현대적인 소프트웨어 배포의 표준으로 만들었습니다.
코드 예제
# Docker 이미지 관리 핵심 명령어
# Docker Hub에서 공식 이미지 다운로드
docker pull node:18-alpine
# 로컬에 있는 모든 이미지 목록 확인
docker images
# 이미지의 상세 정보와 레이어 구조 확인
docker image inspect node:18-alpine
# 이미지 히스토리 - 각 레이어가 어떻게 생성되었는지 확인
docker history node:18-alpine
# 사용하지 않는 이미지 삭제하여 디스크 공간 확보
docker image prune -a
# 특정 이미지에 새 태그 붙이기 - 버전 관리용
docker tag node:18-alpine myapp:v1.0
설명
이것이 하는 일: Docker 이미지는 애플리케이션 실행 환경의 스냅샷을 제공하여, 동일한 컨테이너를 반복적으로 생성할 수 있게 해줍니다. 첫 번째로, docker pull 명령은 Docker Hub(기본 레지스트리)에서 이미지를 다운로드합니다.
node:18-alpine에서 node는 이미지 이름, 18은 Node.js 버전, alpine은 경량 Linux 배포판을 의미합니다. Alpine 기반 이미지는 일반 이미지보다 10배 이상 작아서 다운로드 시간과 저장 공간을 크게 절약합니다.
이미지는 여러 레이어로 구성되어 있어, 이미 존재하는 레이어는 건너뛰고 새로운 레이어만 다운로드합니다. 그 다음으로, docker images는 로컬에 저장된 모든 이미지를 보여줍니다.
여기에는 리포지토리, 태그, 이미지 ID, 생성 시간, 크기가 표시됩니다. docker image inspect는 JSON 형식으로 이미지의 상세 정보를 제공하며, 환경변수, 작업 디렉토리, 포트 설정 등 이미지가 어떻게 구성되었는지 확인할 수 있습니다.
이는 디버깅이나 이미지 분석 시 매우 유용합니다. docker history 명령은 이미지가 어떤 명령어들로 만들어졌는지 역순으로 보여줍니다.
각 레이어가 차지하는 용량도 확인할 수 있어, 이미지 최적화 시 어떤 레이어가 불필요하게 큰지 파악할 수 있습니다. docker tag는 기존 이미지에 새로운 이름이나 버전 태그를 붙이는데, 배포 전에 이미지에 버전을 명시하거나 프라이빗 레지스트리로 푸시하기 전 이름을 변경할 때 사용합니다.
여러분이 이 명령어들을 사용하면 이미지의 생명주기를 완벽하게 관리할 수 있습니다. 개발 단계에서는 최신 이미지를 자주 풀하고, 프로덕션에서는 검증된 특정 버전의 태그를 사용하여 안정성을 확보할 수 있습니다.
또한 정기적으로 불필요한 이미지를 정리하여 디스크 공간을 효율적으로 관리할 수 있으며, 이미지 히스토리를 분석하여 빌드 최적화 포인트를 찾을 수 있습니다.
실전 팁
💡 태그를 명시하지 않으면 자동으로 latest 태그가 사용되지만, 프로덕션에서는 반드시 명시적인 버전 태그를 사용하세요. latest는 예고 없이 변경될 수 있어 위험합니다.
💡 Alpine 기반 이미지는 작지만 일부 라이브러리가 없을 수 있습니다. 호환성 문제가 발생하면 일반 이미지(예: node:18)를 사용하세요.
💡 docker image prune -a --filter "until=24h"로 24시간 이전에 생성된 사용하지 않는 이미지만 선택적으로 삭제할 수 있습니다.
💡 이미지 이름에는 네임스페이스가 포함됩니다. library/node는 공식 이미지이고, username/node는 사용자 이미지입니다. 공식 이미지는 library/ 생략 가능합니다.
💡 docker save와 docker load로 이미지를 파일로 내보내고 가져올 수 있습니다. 인터넷이 없는 환경에서 이미지를 전달할 때 유용합니다.
3. Dockerfile 작성하기 - 나만의 이미지 만들기
시작하며
여러분이 개발한 애플리케이션을 Docker 컨테이너로 실행하고 싶은데, Docker Hub에는 딱 맞는 이미지가 없다면 어떻게 해야 할까요? 단순히 Python이나 Node.js 이미지만으로는 부족하고, 여러분의 코드와 특정 라이브러리, 설정 파일들이 함께 패키징되어야 합니다.
바로 이럴 때 Dockerfile을 직접 작성해야 합니다. Dockerfile은 이미지를 만들기 위한 레시피로, 어떤 베이스 이미지를 사용하고, 어떤 파일을 복사하며, 어떤 명령을 실행할지 정의하는 텍스트 파일입니다.
이를 통해 빌드 과정을 자동화하고, 팀원들과 공유하며, 버전 관리 시스템에서 이미지 변경 이력을 추적할 수 있습니다. Dockerfile을 마스터하면 여러분의 애플리케이션을 어떤 환경에서든 실행 가능한 독립적인 패키지로 만들 수 있습니다.
이것이 바로 진정한 "Build once, run anywhere"의 시작입니다.
개요
간단히 말해서, Dockerfile은 Docker 이미지를 빌드하기 위한 명령어들을 순차적으로 나열한 텍스트 파일로, 인프라를 코드로 정의하는(Infrastructure as Code) 방식입니다. Dockerfile의 각 명령어는 새로운 레이어를 생성합니다.
FROM으로 베이스 이미지를 지정하고, COPY로 파일을 복사하며, RUN으로 명령을 실행하고, CMD로 컨테이너 시작 시 실행할 명령을 지정합니다. 이러한 명령어들이 순서대로 실행되며 최종 이미지가 만들어집니다.
예를 들어, Node.js 애플리케이션을 컨테이너화할 때 베이스 이미지에 의존성을 설치하고, 소스 코드를 복사한 뒤, 애플리케이션을 실행하는 과정을 Dockerfile로 정의할 수 있습니다. 기존에는 서버에 수동으로 소프트웨어를 설치하고 설정했다면, 이제는 Dockerfile로 모든 과정을 코드화하여 자동화하고 반복 가능하게 만들 수 있습니다.
Dockerfile의 핵심 특징은 첫째, 재현성(Reproducibility)입니다. 같은 Dockerfile은 항상 같은 이미지를 생성합니다.
둘째, 버전 관리가 가능합니다. Git으로 Dockerfile을 관리하면 이미지 빌드 과정의 변경 이력을 추적할 수 있습니다.
셋째, 문서화 효과가 있습니다. Dockerfile을 보면 이미지가 어떻게 구성되었는지 한눈에 파악할 수 있습니다.
이러한 특징들이 DevOps 문화의 핵심인 자동화와 투명성을 실현합니다.
코드 예제
# Node.js 18 Alpine 이미지를 베이스로 사용
FROM node:18-alpine
# 컨테이너 내 작업 디렉토리 설정
WORKDIR /app
# package.json과 package-lock.json을 먼저 복사 (캐시 최적화)
COPY package*.json ./
# 의존성 패키지 설치
RUN npm ci --only=production
# 애플리케이션 소스 코드 복사
COPY . .
# 애플리케이션이 사용할 포트 명시 (문서화 목적)
EXPOSE 3000
# 컨테이너 시작 시 실행할 명령
CMD ["node", "server.js"]
설명
이것이 하는 일: Dockerfile은 애플리케이션 환경을 코드로 정의하여, 일관되고 자동화된 방식으로 Docker 이미지를 생성합니다. 첫 번째로, FROM node:18-alpine은 이미지의 시작점을 정의합니다.
모든 Dockerfile은 FROM으로 시작하며, 여기서는 Node.js 18이 설치된 Alpine Linux를 베이스로 사용합니다. Alpine은 5MB 정도로 매우 가벼워 빌드 시간과 이미지 크기를 최소화합니다.
WORKDIR /app은 이후 모든 명령이 실행될 디렉토리를 설정하며, 존재하지 않으면 자동으로 생성됩니다. 이렇게 하는 이유는 파일 구조를 명확히 하고 경로 관리를 단순화하기 위함입니다.
그 다음으로, COPY package*.json ./은 의존성 정의 파일만 먼저 복사합니다. 이것은 Docker의 레이어 캐싱을 활용한 최적화 기법입니다.
소스 코드는 자주 변경되지만 의존성은 상대적으로 변경이 적으므로, 의존성 설치 레이어를 캐시하여 빌드 시간을 크게 단축할 수 있습니다. RUN npm ci --only=production은 package-lock.json을 기반으로 정확한 버전의 의존성을 설치하며, 개발 의존성은 제외하여 이미지 크기를 줄입니다.
COPY . .은 나머지 애플리케이션 소스 코드를 복사합니다.
이 시점에서 .dockerignore 파일에 정의된 파일들(node_modules, .git 등)은 제외됩니다. EXPOSE 3000은 컨테이너가 3000 포트를 사용함을 문서화하는 메타데이터로, 실제로 포트를 여는 것은 아니지만 docker run -P 사용 시 자동 포트 매핑의 기준이 됩니다.
CMD ["node", "server.js"]는 컨테이너 시작 시 실행할 기본 명령을 JSON 배열 형식으로 정의합니다. 여러분이 이 Dockerfile을 사용하면 docker build -t myapp . 명령 한 줄로 애플리케이션 이미지를 빌드할 수 있습니다.
소스 코드를 변경해도 의존성 레이어는 캐시되어 빌드가 빠르며, 팀원 모두가 동일한 Dockerfile로 같은 이미지를 만들 수 있어 "내 컴퓨터에서는 되는데" 문제가 사라집니다. 또한 CI/CD 파이프라인에서 자동으로 이미지를 빌드하고 테스트하여 배포까지 이어지는 완전 자동화된 워크플로우를 구축할 수 있습니다.
실전 팁
💡 .dockerignore 파일을 생성하여 node_modules, .git, 로그 파일 등 불필요한 파일이 이미지에 포함되지 않도록 하세요. 이미지 크기와 빌드 시간이 크게 줄어듭니다.
💡 RUN 명령을 여러 줄로 나누면 레이어가 많아져 캐시 효율이 떨어집니다. &&로 연결하여 하나의 레이어로 만들되, 가독성을 위해 백슬래시(\)로 줄바꿈하세요.
💡 민감한 정보(API 키, 비밀번호)는 절대 Dockerfile이나 이미지에 포함하지 마세요. 대신 환경변수나 Docker secrets을 사용하세요.
💡 멀티스테이지 빌드를 사용하면 빌드 도구는 제외하고 실행 파일만 최종 이미지에 포함시켜 크기를 획기적으로 줄일 수 있습니다.
💡 docker build --no-cache로 캐시 없이 빌드하면 항상 최신 상태로 이미지를 만들 수 있습니다. 프로덕션 빌드 시 권장됩니다.
4. Docker 볼륨과 데이터 관리 - 컨테이너의 영속성 확보
시작하며
여러분이 데이터베이스를 Docker 컨테이너로 실행했는데, 컨테이너를 재시작하니 모든 데이터가 사라져버린 경험이 있나요? 로그 파일을 확인하려는데 컨테이너를 삭제하면서 함께 날아가버렸거나, 개발 중인 코드를 컨테이너 내부에서 수정했더니 컨테이너를 다시 만들 때마다 초기화되는 상황 말이죠.
이런 문제는 컨테이너의 근본적인 특성 때문에 발생합니다. 컨테이너는 기본적으로 임시적(Ephemeral)입니다.
컨테이너 내부에서 생성하거나 수정한 데이터는 컨테이너가 삭제되면 함께 사라집니다. 데이터베이스, 로그, 사용자 업로드 파일 등 영속적으로 보관해야 하는 데이터에는 치명적인 문제입니다.
바로 이럴 때 필요한 것이 Docker 볼륨입니다. 볼륨은 컨테이너의 생명주기와 독립적으로 데이터를 저장하는 메커니즘으로, 컨테이너를 삭제하고 재생성해도 데이터는 안전하게 보존됩니다.
볼륨을 마스터하면 진정한 의미의 프로덕션 환경 컨테이너를 운영할 수 있습니다.
개요
간단히 말해서, Docker 볼륨은 컨테이너와 독립적으로 데이터를 저장하는 공간으로, 호스트 파일시스템에 위치하지만 Docker가 관리하여 이식성과 안정성을 보장합니다. 볼륨에는 세 가지 타입이 있습니다.
첫째, Named Volume은 Docker가 관리하는 영역에 저장되며 가장 권장되는 방식입니다. 둘째, Bind Mount는 호스트의 특정 경로를 컨테이너에 직접 마운트하여 실시간으로 파일을 공유할 수 있습니다.
셋째, tmpfs Mount는 메모리에만 저장되어 민감한 임시 데이터에 적합합니다. 예를 들어, 프로덕션 데이터베이스는 Named Volume을 사용하고, 개발 중인 소스 코드는 Bind Mount로 실시간 반영하며, 세션 토큰은 tmpfs에 저장하는 식으로 용도에 맞게 선택할 수 있습니다.
기존에는 컨테이너 내부에 데이터를 저장하여 컨테이너와 함께 사라졌다면, 이제는 볼륨으로 데이터를 분리하여 컨테이너는 언제든 교체 가능한 실행 단위로, 데이터는 영속적인 자산으로 관리할 수 있습니다. Docker 볼륨의 핵심 특징은 첫째, 영속성(Persistence)입니다.
컨테이너가 삭제되어도 데이터는 보존됩니다. 둘째, 공유 가능(Shareable)합니다.
여러 컨테이너가 동일한 볼륨을 마운트하여 데이터를 공유할 수 있습니다. 셋째, 백업과 마이그레이션이 용이합니다.
볼륨을 통째로 복사하거나 다른 호스트로 이동할 수 있습니다. 이러한 특징들이 컨테이너 기반 스테이트풀(Stateful) 애플리케이션 운영을 가능하게 만듭니다.
코드 예제
# Named Volume 생성
docker volume create my-database-volume
# PostgreSQL 컨테이너를 볼륨과 함께 실행
docker run -d \
--name postgres-db \
-e POSTGRES_PASSWORD=mysecretpassword \
-v my-database-volume:/var/lib/postgresql/data \
-p 5432:5432 \
postgres:15
# Bind Mount로 개발 소스 코드 실시간 반영
docker run -d \
--name dev-app \
-v $(pwd)/src:/app/src \
-p 3000:3000 \
node:18-alpine
# 볼륨 목록 확인 및 상세 정보 조회
docker volume ls
docker volume inspect my-database-volume
# 사용하지 않는 볼륨 정리
docker volume prune
설명
이것이 하는 일: Docker 볼륨은 컨테이너의 임시적 특성과 데이터의 영속성 요구사항을 분리하여, 안전하고 유연한 데이터 관리를 제공합니다. 첫 번째로, docker volume create는 Named Volume을 명시적으로 생성합니다.
이 볼륨은 Docker가 관리하는 영역(/var/lib/docker/volumes/)에 저장되며, 직접 경로를 지정하지 않아도 Docker가 알아서 관리합니다. PostgreSQL 컨테이너 실행 시 -v my-database-volume:/var/lib/postgresql/data로 볼륨을 마운트하는데, 콜론(:) 앞은 볼륨 이름, 뒤는 컨테이너 내부 경로입니다.
PostgreSQL은 /var/lib/postgresql/data에 데이터베이스 파일을 저장하므로, 이 경로를 볼륨으로 마운트하면 컨테이너를 삭제해도 데이터는 볼륨에 남습니다. 그 다음으로, Bind Mount 예제에서 -v $(pwd)/src:/app/src는 현재 디렉토리의 src 폴더를 컨테이너의 /app/src에 직접 연결합니다.
호스트에서 파일을 수정하면 즉시 컨테이너 내부에 반영되므로, 코드 변경 후 재빌드 없이 Hot Reload가 가능합니다. 이는 개발 생산성을 크게 향상시키지만, 프로덕션에서는 보안과 성능 문제로 Named Volume을 사용해야 합니다.
docker volume inspect는 볼륨의 상세 정보를 JSON 형식으로 보여주며, 실제 저장 경로(Mountpoint), 생성 시간, 사용 중인 컨테이너 등을 확인할 수 있습니다. docker volume prune은 어떤 컨테이너에도 연결되지 않은 볼륨을 삭제하여 디스크 공간을 확보합니다.
단, 이 명령은 주의해서 사용해야 하며, 중요한 데이터가 포함된 볼륨은 별도로 백업해두어야 합니다. 여러분이 볼륨을 사용하면 데이터베이스 컨테이너를 업데이트할 때 데이터 손실 없이 새 버전으로 교체할 수 있습니다.
예를 들어, PostgreSQL 14에서 15로 업그레이드할 때 기존 컨테이너를 중지하고 삭제한 뒤, 같은 볼륨을 마운트한 새 컨테이너를 실행하면 됩니다. 또한 개발 환경에서는 Bind Mount로 소스 코드를 실시간 반영하여 빠른 피드백 루프를 만들고, 로그 파일을 볼륨에 저장하여 컨테이너 종료 후에도 분석할 수 있습니다.
실전 팁
💡 Named Volume은 자동으로 생성되므로 docker volume create 없이도 -v 옵션에서 바로 사용할 수 있습니다. 하지만 명시적으로 생성하는 것이 관리에 유리합니다.
💡 Bind Mount 사용 시 절대 경로를 사용하거나 $(pwd)로 현재 경로를 명확히 지정하세요. 상대 경로는 예상치 못한 결과를 초래할 수 있습니다.
💡 볼륨 백업은 docker run --rm -v my-volume:/data -v $(pwd):/backup alpine tar czf /backup/backup.tar.gz /data로 할 수 있습니다.
💡 여러 컨테이너가 같은 볼륨을 마운트할 때는 읽기 전용(:ro) 옵션을 활용하여 의도치 않은 데이터 변경을 방지하세요.
💡 Docker Compose에서는 volumes: 섹션으로 볼륨을 정의하고 여러 서비스에서 재사용할 수 있어 더 편리합니다.
5. Docker 네트워킹 - 컨테이너 간 통신
시작하며
여러분이 웹 애플리케이션 컨테이너와 데이터베이스 컨테이너를 각각 실행했는데, 두 컨테이너가 서로 통신할 수 없어서 애플리케이션이 데이터베이스에 접속하지 못하는 상황을 겪어본 적 있나요? 컨테이너 IP 주소를 하드코딩했더니 컨테이너를 재시작할 때마다 IP가 바뀌어 연결이 끊기거나, 외부에서 접근해야 하는 API 서버가 격리되어 있어 접근할 수 없는 경우 말이죠.
이런 문제는 Docker 네트워킹을 제대로 이해하지 못해서 발생합니다. 컨테이너는 기본적으로 격리된 네트워크 환경을 가지며, 명시적으로 연결하지 않으면 서로 통신할 수 없습니다.
마이크로서비스 아키텍처에서는 수십 개의 컨테이너가 서로 통신해야 하므로, 네트워킹 설정이 매우 중요합니다. Docker 네트워킹을 마스터하면 컨테이너들을 논리적으로 그룹화하고, 서비스 이름으로 통신하며, 외부 노출을 제어하여 안전하고 유연한 아키텍처를 구축할 수 있습니다.
네트워크는 컨테이너 오케스트레이션의 핵심 요소입니다.
개요
간단히 말해서, Docker 네트워크는 컨테이너들이 서로, 그리고 외부와 통신할 수 있도록 하는 가상 네트워크 인프라로, 격리, 연결, 보안을 제공합니다. Docker는 여러 네트워크 드라이버를 제공합니다.
첫째, Bridge 네트워크는 기본 네트워크로 같은 호스트의 컨테이너들을 연결합니다. 둘째, Host 네트워크는 컨테이너가 호스트의 네트워크를 직접 사용하여 최고의 성능을 제공합니다.
셋째, Overlay 네트워크는 여러 Docker 호스트에 걸친 컨테이너들을 연결하여 분산 환경을 지원합니다. 예를 들어, 개발 환경에서는 사용자 정의 Bridge 네트워크로 웹 서버와 데이터베이스를 연결하고, 프로덕션에서는 Overlay 네트워크로 여러 서버의 컨테이너를 하나의 클러스터로 구성할 수 있습니다.
기존에는 컨테이너 IP를 직접 찾아서 연결했다면, 이제는 사용자 정의 네트워크를 만들고 컨테이너 이름으로 DNS 기반 통신을 할 수 있습니다. Docker 네트워킹의 핵심 특징은 첫째, 자동 DNS 해석입니다.
사용자 정의 네트워크에서는 컨테이너 이름이 자동으로 호스트명이 됩니다. 둘째, 네트워크 격리입니다.
다른 네트워크의 컨테이너는 기본적으로 통신할 수 없어 보안이 강화됩니다. 셋째, 유연한 연결입니다.
컨테이너를 여러 네트워크에 동시에 연결할 수 있습니다. 이러한 특징들이 마이크로서비스 간의 안전하고 유연한 통신을 가능하게 합니다.
코드 예제
# 사용자 정의 Bridge 네트워크 생성
docker network create my-app-network
# 네트워크에 데이터베이스 컨테이너 연결
docker run -d \
--name postgres-db \
--network my-app-network \
-e POSTGRES_PASSWORD=secret \
postgres:15
# 같은 네트워크에 웹 애플리케이션 연결
# 컨테이너 이름 'postgres-db'로 데이터베이스 접근 가능
docker run -d \
--name web-app \
--network my-app-network \
-p 8080:3000 \
-e DATABASE_URL=postgresql://postgres:secret@postgres-db:5432/mydb \
my-web-app:latest
# 네트워크 목록 및 상세 정보 확인
docker network ls
docker network inspect my-app-network
# 실행 중인 컨테이너를 네트워크에 연결/해제
docker network connect my-app-network existing-container
docker network disconnect my-app-network existing-container
설명
이것이 하는 일: Docker 네트워크는 컨테이너들을 논리적으로 연결하고 격리하여, 서비스 간 안전하고 편리한 통신을 가능하게 합니다. 첫 번째로, docker network create로 사용자 정의 Bridge 네트워크를 생성합니다.
기본 bridge 네트워크와 달리 사용자 정의 네트워크는 자동 DNS 해석을 제공하여, 컨테이너 이름으로 다른 컨테이너에 접근할 수 있습니다. 이렇게 하는 이유는 IP 주소는 컨테이너 재시작 시 변경될 수 있지만, 이름은 일정하게 유지되어 안정적인 통신이 가능하기 때문입니다.
그 다음으로, --network my-app-network 옵션으로 컨테이너를 네트워크에 연결합니다. PostgreSQL 컨테이너의 이름이 postgres-db이므로, 웹 애플리케이션에서 DATABASE_URL에 postgres-db를 호스트명으로 사용할 수 있습니다.
Docker의 내장 DNS 서버가 postgres-db를 해당 컨테이너의 IP로 자동 해석합니다. -p 8080:3000은 웹 애플리케이션을 외부에 노출하지만, 데이터베이스는 포트를 노출하지 않아 같은 네트워크의 컨테이너만 접근할 수 있어 보안이 강화됩니다.
docker network inspect는 네트워크에 연결된 모든 컨테이너와 각각의 IP 주소, 서브넷 설정 등을 JSON 형식으로 보여줍니다. 네트워크 문제를 디버깅할 때 매우 유용합니다.
docker network connect와 disconnect는 실행 중인 컨테이너를 동적으로 네트워크에 연결하거나 해제할 수 있어, 컨테이너를 재시작하지 않고도 네트워크 구성을 변경할 수 있습니다. 여러분이 사용자 정의 네트워크를 사용하면 마이크로서비스 아키텍처를 쉽게 구현할 수 있습니다.
예를 들어, 프론트엔드, 백엔드, 데이터베이스를 각각 컨테이너로 실행하고 하나의 네트워크로 연결하면, 각 서비스는 서로의 이름으로 통신합니다. 외부에는 프론트엔드만 노출하고 나머지는 네트워크 내부에 숨겨 보안을 강화할 수 있습니다.
또한 개발 환경과 프로덕션 환경에서 동일한 컨테이너 이름을 사용하여 코드 변경 없이 배포할 수 있습니다.
실전 팁
💡 기본 bridge 네트워크 대신 항상 사용자 정의 네트워크를 만들어 사용하세요. 자동 DNS와 더 나은 격리가 제공됩니다.
💡 컨테이너를 여러 네트워크에 연결하여 프론트엔드 네트워크와 백엔드 네트워크를 분리하는 등 계층화된 아키텍처를 만들 수 있습니다.
💡 docker run --network host를 사용하면 최고 성능을 얻지만 격리가 없어집니다. 성능이 매우 중요한 경우에만 사용하세요.
💡 네트워크 드라이버 옵션(--driver)으로 overlay, macvlan 등 다양한 네트워크 유형을 선택할 수 있습니다. 기본은 bridge입니다.
💡 Docker Compose는 자동으로 프로젝트별 네트워크를 생성하여 서비스 간 통신을 간단하게 만들어줍니다. 프로덕션에서는 Compose 사용을 권장합니다.
6. Docker Compose 입문 - 멀티 컨테이너 애플리케이션 관리
시작하며
여러분이 웹 애플리케이션, 데이터베이스, Redis 캐시, Nginx 리버스 프록시를 모두 컨테이너로 실행해야 한다면, docker run 명령을 4번 입력하고 네트워크를 만들고 볼륨을 연결하는 긴 명령어들을 매번 타이핑해야 할까요? 팀원이 프로젝트를 클론해서 실행하려면 복잡한 README를 따라 명령어를 하나씩 실행해야 하고, 한 단계라도 빠뜨리면 전체가 작동하지 않는 상황이 발생합니다.
이런 복잡성은 실무에서 큰 문제가 됩니다. 컨테이너가 많아질수록 관리가 어려워지고, 환경변수나 포트 설정을 변경할 때마다 여러 명령어를 수정해야 하며, 전체 스택을 한 번에 시작하거나 중지하기도 힘듭니다.
Docker Compose가 바로 이 문제의 해결책입니다. YAML 파일 하나로 멀티 컨테이너 애플리케이션의 모든 구성을 정의하고, 단 한 줄의 명령으로 전체 스택을 실행할 수 있습니다.
인프라를 코드로 관리하는 진정한 Infrastructure as Code의 시작입니다.
개요
간단히 말해서, Docker Compose는 여러 컨테이너로 구성된 애플리케이션을 YAML 파일로 정의하고, 단일 명령으로 전체 환경을 생성하고 관리하는 도구입니다. docker-compose.yml 파일에서 services, networks, volumes를 선언적으로 정의합니다.
각 서비스는 컨테이너 하나에 대응하며, 이미지, 환경변수, 포트, 볼륨, 의존성 등을 명시합니다. Compose는 자동으로 서비스들을 위한 네트워크를 생성하고, 서비스 이름으로 DNS 해석을 제공합니다.
예를 들어, WordPress와 MySQL을 함께 실행하는 스택을 정의하면, 두 서비스는 자동으로 같은 네트워크에 배치되어 서로 통신할 수 있습니다. 의존성 순서도 자동으로 관리되어 MySQL이 먼저 시작된 후 WordPress가 실행됩니다.
기존에는 긴 docker run 명령어를 쉘 스크립트로 관리했다면, 이제는 선언적 YAML 파일로 원하는 상태를 정의하고 Compose가 자동으로 그 상태를 만들어줍니다. Docker Compose의 핵심 특징은 첫째, 선언적 정의입니다.
"어떻게"가 아닌 "무엇을" 원하는지 기술합니다. 둘째, 단일 명령 실행입니다.
docker-compose up 하나로 전체 스택이 시작됩니다. 셋째, 환경 격리입니다.
프로젝트별로 독립된 네트워크와 볼륨을 자동 생성합니다. 넷째, 재현 가능성입니다.
같은 YAML 파일은 어디서든 동일한 환경을 만듭니다. 이러한 특징들이 로컬 개발 환경 구성의 표준이 되었습니다.
코드 예제
# docker-compose.yml 파일 내용
version: '3.8'
services:
# 웹 애플리케이션 서비스
web:
build: .
ports:
- "3000:3000"
environment:
- DATABASE_URL=postgresql://postgres:secret@db:5432/myapp
- REDIS_URL=redis://cache:6379
depends_on:
- db
- cache
volumes:
- ./src:/app/src # 개발 중 소스 코드 hot reload
# PostgreSQL 데이터베이스
db:
image: postgres:15-alpine
environment:
- POSTGRES_PASSWORD=secret
- POSTGRES_DB=myapp
volumes:
- db-data:/var/lib/postgresql/data
# Redis 캐시
cache:
image: redis:7-alpine
volumes:
db-data: # Named volume 정의
# 명령어 사용법
# docker-compose up -d # 백그라운드로 전체 스택 시작
# docker-compose logs -f # 전체 로그 실시간 확인
# docker-compose down # 전체 스택 중지 및 삭제
설명
이것이 하는 일: Docker Compose는 여러 컨테이너의 복잡한 구성을 코드화하여, 일관되고 재현 가능한 개발 환경을 단 한 줄의 명령으로 제공합니다. 첫 번째로, version: '3.8'은 Compose 파일 형식 버전을 지정합니다.
각 버전마다 지원하는 기능이 다르므로 최신 버전 사용을 권장합니다. services: 섹션에서 각 컨테이너를 정의하는데, web 서비스는 현재 디렉토리의 Dockerfile을 빌드(build: .)하고, db와 cache는 공식 이미지를 사용합니다.
이렇게 하는 이유는 커스텀 애플리케이션은 빌드해야 하지만, 표준 서비스는 검증된 공식 이미지를 사용하는 것이 안전하고 효율적이기 때문입니다. 그 다음으로, environment: 섹션에서 환경변수를 정의합니다.
DATABASE_URL의 호스트명으로 db를 사용하는데, Compose가 자동으로 생성한 네트워크 내에서 서비스 이름이 DNS 호스트명이 되기 때문입니다. depends_on:은 서비스 시작 순서를 제어하여 db와 cache가 먼저 시작된 후 web이 시작되도록 합니다.
단, 이는 컨테이너 시작 순서만 제어하며, 실제 서비스가 준비되었는지는 확인하지 않습니다. 프로덕션에서는 health check나 재시도 로직이 필요합니다.
volumes: 섹션은 두 가지 용도로 사용됩니다. 서비스 레벨의 ./src:/app/src는 Bind Mount로 소스 코드를 실시간 반영하여 개발 생산성을 높이고, db-data:/var/lib/postgresql/data는 Named Volume으로 데이터베이스 데이터를 영속화합니다.
최상위 volumes: 섹션에서 db-data를 선언하면 Compose가 자동으로 생성하고 관리합니다. 여러분이 Docker Compose를 사용하면 docker-compose up -d 한 줄로 전체 개발 환경이 준비됩니다.
팀원이 프로젝트를 클론하고 Compose 파일만 실행하면 즉시 동일한 환경을 얻습니다. docker-compose logs -f web으로 특정 서비스의 로그를 확인하고, docker-compose restart web으로 하나의 서비스만 재시작하는 등 세밀한 제어가 가능합니다.
환경변수나 포트를 변경할 때도 YAML 파일만 수정하면 되어 유지보수가 편리합니다. 또한 .env 파일로 민감한 정보를 분리하여 버전 관리에서 제외할 수 있습니다.
실전 팁
💡 .env 파일을 프로젝트 루트에 만들면 Compose가 자동으로 읽어서 환경변수로 사용합니다. 비밀번호 같은 민감 정보는 여기에 저장하고 .gitignore에 추가하세요.
💡 docker-compose up --build로 이미지를 강제로 재빌드할 수 있습니다. Dockerfile을 변경한 후에는 꼭 사용하세요.
💡 docker-compose down -v는 볼륨까지 삭제합니다. 개발 중 데이터베이스를 완전히 초기화하고 싶을 때 유용하지만, 프로덕션에서는 절대 사용하지 마세요.
💡 여러 Compose 파일을 조합할 수 있습니다. docker-compose -f docker-compose.yml -f docker-compose.prod.yml up으로 환경별 설정을 분리하세요.
💡 docker-compose exec web sh로 실행 중인 서비스 컨테이너에 접속할 수 있습니다. 디버깅이나 데이터베이스 마이그레이션 실행 시 유용합니다.
7. 컨테이너 환경변수와 설정 관리 - 보안과 유연성의 핵심
시작하며
여러분이 개발한 애플리케이션을 개발, 스테이징, 프로덕션 환경에 배포할 때마다 코드를 수정해서 데이터베이스 주소나 API 키를 바꾸고 계신가요? 비밀번호나 API 키를 Dockerfile이나 소스 코드에 하드코딩해서 Git에 커밋했다가, 나중에 보안 문제를 발견하고 이미 공개된 커밋 히스토리를 정리하느라 고생한 경험이 있나요?
이런 문제는 설정과 코드를 분리하지 않아서 발생합니다. The Twelve-Factor App 방법론에서도 강조하듯이, 설정(특히 환경마다 다른 값)은 코드와 엄격히 분리되어야 합니다.
하드코딩된 설정은 보안 위험이며, 환경을 바꿀 때마다 재빌드가 필요하고, 실수로 잘못된 환경의 설정을 사용할 위험이 있습니다. Docker의 환경변수 메커니즘이 바로 이 문제의 해결책입니다.
환경변수로 설정을 주입하면 동일한 이미지를 모든 환경에서 사용하면서도 환경별로 다른 동작을 할 수 있습니다. 이것이 바로 진정한 "Build once, run anywhere"를 실현하는 방법입니다.
개요
간단히 말해서, Docker 환경변수는 컨테이너 실행 시 외부에서 주입하는 키-값 쌍으로, 코드 변경 없이 애플리케이션의 동작을 제어하고 민감한 정보를 안전하게 전달하는 메커니즘입니다. 환경변수는 여러 방법으로 전달할 수 있습니다.
첫째, -e 플래그로 명령줄에서 직접 전달할 수 있습니다. 둘째, --env-file로 파일에서 읽을 수 있습니다.
셋째, Docker Compose의 environment: 섹션에서 정의하거나 .env 파일을 사용할 수 있습니다. 넷째, Docker Secrets나 Kubernetes ConfigMap 같은 고급 메커니즘도 있습니다.
예를 들어, 로컬 개발에서는 .env 파일을 사용하고, 프로덕션에서는 Docker Swarm Secrets나 AWS Secrets Manager를 사용하여 민감 정보를 안전하게 관리할 수 있습니다. 기존에는 설정 파일을 환경마다 따로 만들고 배포 시 교체했다면, 이제는 환경변수만 바꿔서 동일한 컨테이너 이미지를 모든 환경에서 재사용할 수 있습니다.
Docker 환경변수의 핵심 특징은 첫째, 코드와 설정의 분리입니다. 12 Factor App 원칙을 따라 환경별 차이를 외부화합니다.
둘째, 보안 강화입니다. 민감 정보를 코드나 이미지에 포함하지 않아 유출 위험이 줄어듭니다.
셋째, 이미지 재사용성입니다. 하나의 이미지를 모든 환경에서 사용하여 "스테이징에서 테스트한 것과 프로덕션이 다르다"는 문제를 방지합니다.
이러한 특징들이 안전하고 유연한 배포 전략을 가능하게 합니다.
코드 예제
# 명령줄에서 환경변수 직접 전달
docker run -d \
--name my-app \
-e NODE_ENV=production \
-e DATABASE_URL=postgresql://user:pass@db:5432/mydb \
-e API_KEY=sk-1234567890abcdef \
-p 3000:3000 \
my-app:latest
# .env 파일 사용 - 민감 정보를 파일로 관리
# 파일 내용: NODE_ENV=production
# DATABASE_URL=postgresql://...
# API_KEY=sk-...
docker run -d --name my-app --env-file .env -p 3000:3000 my-app:latest
# Dockerfile에서 환경변수 기본값 설정
# ENV NODE_ENV=development
# ENV PORT=3000
# 애플리케이션 코드에서 환경변수 읽기 (Node.js 예제)
# const dbUrl = process.env.DATABASE_URL || 'postgresql://localhost:5432/dev';
# const apiKey = process.env.API_KEY;
# if (!apiKey) throw new Error('API_KEY is required');
설명
이것이 하는 일: 환경변수는 컨테이너에 외부 설정을 주입하여, 코드나 이미지를 변경하지 않고도 애플리케이션의 동작을 환경에 맞게 조정합니다. 첫 번째로, -e 플래그는 환경변수를 개별적으로 지정합니다.
NODE_ENV=production은 Node.js 애플리케이션에 프로덕션 모드로 실행하라고 알려주며, 이 모드에서는 디버그 로그가 비활성화되고 최적화가 활성화됩니다. DATABASE_URL은 데이터베이스 연결 문자열로, 환경마다 다른 데이터베이스 서버를 가리킬 수 있습니다.
이렇게 하는 이유는 개발에서는 로컬 데이터베이스를, 프로덕션에서는 클라우드 데이터베이스를 사용하면서도 동일한 코드와 이미지를 사용하기 위함입니다. 그 다음으로, --env-file 옵션은 환경변수를 파일에서 읽어옵니다.
.env 파일은 각 줄에 KEY=VALUE 형식으로 작성되며, 민감한 정보를 명령 히스토리에 남기지 않고 파일로 관리할 수 있습니다. 이 파일은 반드시 .gitignore에 추가하여 버전 관리에서 제외해야 합니다.
대신 .env.example 파일을 만들어 필요한 환경변수 목록을 팀원들에게 공유하고, 각자 자신의 .env 파일을 만들도록 합니다. Dockerfile의 ENV 명령어는 이미지에 기본 환경변수를 설정합니다.
이 값은 컨테이너 실행 시 -e 옵션으로 오버라이드할 수 있습니다. 애플리케이션 코드에서는 process.env.DATABASE_URL (Node.js), os.environ.get('DATABASE_URL') (Python) 같은 방식으로 환경변수를 읽습니다.
필수 환경변수가 없으면 즉시 에러를 발생시켜 잘못된 설정으로 실행되는 것을 방지하는 것이 좋은 패턴입니다. 여러분이 환경변수를 올바르게 사용하면 개발 환경에서 로컬 데이터베이스로 테스트하고, 스테이징에서 테스트 데이터베이스로 검증한 뒤, 같은 이미지를 프로덕션 데이터베이스로 배포할 수 있습니다.
이미지는 한 번만 빌드되고 CI/CD 파이프라인을 통해 검증되므로, "스테이징에서는 되는데 프로덕션에서 안 된다"는 문제가 사라집니다. 또한 API 키나 비밀번호를 코드에서 완전히 분리하여 보안을 강화하고, 로테이션(주기적 변경) 시에도 재빌드 없이 새 값만 주입하면 됩니다.
실전 팁
💡 절대 Dockerfile의 ENV나 ARG에 민감 정보를 넣지 마세요. 이미지 레이어에 영구적으로 저장되어 docker history로 볼 수 있습니다.
💡 환경변수 이름은 대문자와 언더스코어를 사용하는 것이 관례입니다(예: DATABASE_URL, API_KEY). 일관성이 중요합니다.
💡 docker run 시 -e KEY처럼 값 없이 지정하면, 호스트의 환경변수 값을 그대로 전달합니다. CI/CD 환경에서 유용합니다.
💡 Docker Compose에서 ${VARIABLE:-default} 문법으로 기본값을 지정할 수 있습니다. 환경변수가 없을 때 대비책을 만드세요.
💡 프로덕션에서는 Docker Secrets, Kubernetes Secrets, AWS Secrets Manager 같은 전문 비밀 관리 도구를 사용하세요. 단순 환경변수보다 훨씬 안전합니다.
8. 컨테이너 로그 관리와 디버깅 - 문제 해결의 시작점
시작하며
여러분이 프로덕션 환경에서 컨테이너가 예기치 않게 종료되거나 오류를 발생시키는데, 무슨 일이 일어났는지 알 방법이 없어서 막막했던 경험이 있나요? 애플리케이션이 정상적으로 작동하지 않는데 로그를 어디서 확인해야 할지 몰라서, 또는 로그가 너무 많아서 필요한 정보를 찾지 못해서 디버깅에 몇 시간을 허비한 적이 있나요?
컨테이너 환경에서 로그는 더욱 중요합니다. 전통적인 서버에서는 로그 파일을 직접 열어볼 수 있지만, 컨테이너는 임시적이고 격리되어 있어 표준 출력(stdout)과 표준 에러(stderr)로 로그를 내보내야 합니다.
컨테이너가 종료되면 내부 파일은 사라지지만, Docker가 수집한 로그는 호스트에 남아 있어 사후 분석이 가능합니다. Docker의 로그 관리 메커니즘을 마스터하면 문제를 빠르게 진단하고, 애플리케이션 동작을 모니터링하며, 프로덕션 이슈를 신속하게 해결할 수 있습니다.
로그는 운영의 눈과 귀입니다.
개요
간단히 말해서, Docker 로그는 컨테이너의 표준 출력과 표준 에러를 수집하여 저장하는 메커니즘으로, 애플리케이션의 상태를 추적하고 문제를 진단하는 핵심 도구입니다. Docker는 다양한 로그 드라이버를 지원합니다.
기본 json-file 드라이버는 로그를 JSON 형식으로 로컬에 저장하며, docker logs 명령으로 쉽게 확인할 수 있습니다. syslog, journald 드라이버는 시스템 로그와 통합되고, fluentd, gelf, awslogs 같은 드라이버는 중앙 집중식 로그 수집 시스템으로 전송합니다.
예를 들어, 개발 환경에서는 json-file로 간단하게 로그를 보고, 프로덕션에서는 awslogs로 CloudWatch에 전송하여 장기 보관하고 분석할 수 있습니다. 기존에는 서버에 SSH로 접속해서 로그 파일을 직접 열어봤다면, 이제는 어디서든 docker logs 명령으로 즉시 로그를 확인하고, 필터링하고, 실시간으로 추적할 수 있습니다.
Docker 로그의 핵심 특징은 첫째, 표준화입니다. 모든 컨테이너의 로그를 동일한 방식으로 수집하고 접근합니다.
둘째, 중앙 집중식 관리가 가능합니다. 로그 드라이버로 ELK Stack, Splunk, CloudWatch 같은 시스템과 통합할 수 있습니다.
셋째, 컨테이너 종료 후에도 로그가 보존됩니다. 넷째, 실시간 모니터링이 가능합니다.
docker logs -f로 로그를 계속 추적할 수 있습니다. 이러한 특징들이 컨테이너 기반 애플리케이션의 관찰 가능성(Observability)을 제공합니다.
코드 예제
# 컨테이너 로그 기본 확인
docker logs my-container
# 실시간 로그 추적 (tail -f와 유사)
docker logs -f my-container
# 최근 100줄만 확인
docker logs --tail 100 my-container
# 타임스탬프와 함께 로그 확인
docker logs -t my-container
# 특정 시간 이후의 로그만 확인
docker logs --since 2025-01-01T10:00:00 my-container
docker logs --since 30m my-container # 최근 30분
# 여러 컨테이너의 로그를 동시에 확인 (Docker Compose)
docker-compose logs -f web db
# 로그 드라이버 설정 (awslogs 예제)
docker run -d \
--log-driver=awslogs \
--log-opt awslogs-region=us-east-1 \
--log-opt awslogs-group=my-app-logs \
--log-opt awslogs-stream=container-1 \
my-app:latest
설명
이것이 하는 일: Docker 로그는 컨테이너의 모든 출력을 캡처하여, 애플리케이션의 동작을 이해하고 문제를 진단할 수 있는 정보를 제공합니다. 첫 번째로, docker logs my-container는 컨테이너의 전체 로그를 표시합니다.
이는 컨테이너 시작부터 현재까지의 모든 표준 출력과 표준 에러를 보여주며, 컨테이너가 중지되어도 로그는 호스트에 저장되어 있어 확인할 수 있습니다. 이렇게 하는 이유는 컨테이너 내부 파일시스템에 접근하지 않고도 애플리케이션의 동작을 추적하기 위함입니다.
-f 플래그는 tail -f처럼 실시간으로 새 로그를 계속 표시하며, 개발 중이나 문제 발생 시 즉시 피드백을 받을 수 있습니다. 그 다음으로, --tail 100은 최근 100줄만 표시하여 긴 로그에서 최신 정보만 빠르게 확인할 수 있습니다.
-t 옵션은 각 로그 줄에 타임스탬프를 추가하여 언제 발생한 일인지 정확히 파악할 수 있습니다. --since 옵션은 특정 시간 이후의 로그만 필터링하는데, --since 30m은 최근 30분, --since 2h는 최근 2시간의 로그를 의미합니다.
이는 특정 시점에 발생한 문제를 추적할 때 매우 유용합니다. Docker Compose 환경에서는 docker-compose logs로 여러 서비스의 로그를 동시에 확인할 수 있으며, 서비스 이름으로 구분되어 표시됩니다.
--log-driver 옵션은 로그를 어디에 저장할지 지정하는데, awslogs는 AWS CloudWatch로, fluentd는 Fluentd 서버로, gelf는 Graylog로 전송합니다. 프로덕션 환경에서는 중앙 집중식 로그 시스템을 사용하여 수백 개 컨테이너의 로그를 한곳에서 검색하고 분석할 수 있습니다.
여러분이 Docker 로그를 효과적으로 사용하면 애플리케이션이 예상치 못하게 종료되었을 때 docker logs로 마지막 오류 메시지를 확인하여 원인을 파악할 수 있습니다. 실시간 로그 추적으로 API 요청이 어떻게 처리되는지 모니터링하고, 타임스탬프로 특정 시간에 발생한 이벤트를 연결하며, 중앙 로그 시스템과 통합하여 분산 트레이싱과 메트릭 수집을 구현할 수 있습니다.
또한 로그를 분석하여 성능 병목지점을 찾고, 사용 패턴을 이해하며, 보안 이벤트를 감지할 수 있습니다.
실전 팁
💡 프로덕션에서는 json-file 드라이버의 max-size와 max-file 옵션으로 로그 크기를 제한하세요. 무제한 로그는 디스크를 가득 채울 수 있습니다.
💡 애플리케이션은 로그를 파일이 아닌 stdout/stderr로 출력하도록 설정하세요. 이것이 12 Factor App의 로그 원칙입니다.
💡 grep, awk 같은 Unix 도구와 조합하여 로그를 필터링하세요. 예: docker logs my-app | grep ERROR
💡 구조화된 로그(JSON 형식)를 사용하면 중앙 로그 시스템에서 필드별 검색과 집계가 가능해져 분석이 훨씬 수월합니다.
💡 민감한 정보(비밀번호, API 키)가 로그에 출력되지 않도록 주의하세요. 로그는 여러 곳에 복제되어 유출 위험이 있습니다.
9. Docker 이미지 최적화 - 크기와 빌드 시간 줄이기
시작하며
여러분이 만든 Docker 이미지가 2GB가 넘어서 빌드와 배포에 10분 이상 걸리고, CI/CD 파이프라인이 느려지며, 컨테이너 레지스트리 저장 비용이 계속 증가하는 상황을 겪고 계신가요? 작은 코드 변경에도 전체 이미지를 다시 빌드해야 해서 개발 속도가 느려지거나, 프로덕션 배포 시 큰 이미지를 다운로드하느라 서비스 시작이 지연되는 문제 말이죠.
비대한 이미지는 여러 문제를 야기합니다. 네트워크 전송 시간이 늘어나고, 저장 공간을 낭비하며, 공격 표면(Attack Surface)이 넓어져 보안 취약점이 증가하고, 컨테이너 시작 시간도 길어집니다.
특히 마이크로서비스 아키텍처에서 수십 개의 컨테이너를 운영할 때 이미지 크기는 전체 시스템 성능에 직접적인 영향을 미칩니다. Docker 이미지 최적화 기법을 마스터하면 이미지 크기를 10분의 1로 줄이고, 빌드 시간을 크게 단축하며, 배포 속도를 획기적으로 개선할 수 있습니다.
최적화는 성능과 비용, 보안까지 개선하는 필수 기술입니다.
개요
간단히 말해서, Docker 이미지 최적화는 불필요한 레이어와 파일을 제거하고, 효율적인 빌드 전략을 사용하여 이미지 크기를 최소화하고 빌드 속도를 극대화하는 일련의 기법들입니다. 최적화의 핵심 전략은 여러 가지입니다.
첫째, 작은 베이스 이미지 사용입니다. Ubuntu(80MB) 대신 Alpine(5MB)을 사용하면 크기가 16배 줄어듭니다.
둘째, 멀티스테이지 빌드입니다. 빌드 도구와 의존성은 빌드 단계에만 포함하고, 최종 이미지에는 실행 파일만 복사합니다.
셋째, 레이어 최적화입니다. 자주 변경되는 레이어를 나중에 배치하여 캐시 효율을 높입니다.
넷째, .dockerignore 사용입니다. 불필요한 파일이 이미지에 포함되는 것을 방지합니다.
예를 들어, Go 애플리케이션을 빌드할 때 빌드 스테이지에서는 Go 컴파일러가 포함된 golang 이미지를 사용하고, 최종 스테이지에서는 scratch나 alpine 이미지에 실행 파일만 복사하면 이미지 크기가 1GB에서 10MB로 줄어들 수 있습니다. 기존에는 하나의 Dockerfile로 빌드와 실행을 모두 포함했다면, 이제는 멀티스테이지 빌드로 빌드 환경과 실행 환경을 완전히 분리하여 최종 이미지를 최소화할 수 있습니다.
이미지 최적화의 핵심 특징은 첫째, 크기 감소입니다. 작은 이미지는 전송과 시작이 빠릅니다.
둘째, 보안 향상입니다. 불필요한 패키지와 도구를 제거하여 취약점을 줄입니다.
셋째, 빌드 속도 향상입니다. 캐시를 활용하여 변경되지 않은 레이어는 재사용합니다.
넷째, 비용 절감입니다. 저장 공간과 전송 대역폭을 절약합니다.
이러한 특징들이 효율적인 컨테이너 운영의 기반이 됩니다.
코드 예제
# 멀티스테이지 빌드 - Node.js 애플리케이션 예제
# 빌드 스테이지: 의존성 설치 및 빌드
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
# 최종 스테이지: 실행에 필요한 것만 포함
FROM node:18-alpine
WORKDIR /app
# 빌드 스테이지에서 결과물만 복사
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
# 불필요한 devDependencies와 소스 파일 제외
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]
# .dockerignore 파일 내용
# node_modules
# npm-debug.log
# .git
# .env
# *.md
# tests/
# .vscode/
설명
이것이 하는 일: 이미지 최적화는 불필요한 요소를 제거하고 효율적인 구조를 사용하여, 빠르고 안전하며 경제적인 컨테이너 이미지를 만듭니다. 첫 번째로, 멀티스테이지 빌드는 FROM 명령을 여러 번 사용합니다.
첫 번째 FROM node:18-alpine AS builder는 빌드 스테이지로, 여기서는 모든 의존성을 설치하고 TypeScript를 컴파일하여 JavaScript로 변환합니다. AS builder로 이 스테이지에 이름을 붙여 나중에 참조할 수 있게 합니다.
이 스테이지에는 TypeScript 컴파일러, 개발 도구, 테스트 프레임워크 등이 포함되어 크기가 큽니다. 이렇게 하는 이유는 빌드에 필요한 모든 도구를 사용하면서도 최종 이미지에는 포함하지 않기 위함입니다.
그 다음으로, 두 번째 FROM node:18-alpine은 최종 스테이지로, 깨끗한 Alpine 이미지에서 시작합니다. COPY --from=builder는 이전 빌드 스테이지에서 결과물만 복사합니다.
dist 폴더(컴파일된 JavaScript)와 node_modules(프로덕션 의존성)만 가져오고, 소스 코드(TypeScript 파일), 빌드 도구, 테스트 파일은 제외됩니다. 결과적으로 최종 이미지에는 실행에 필요한 것만 포함되어 크기가 500MB에서 100MB 이하로 줄어듭니다.
USER node는 보안을 위해 root가 아닌 일반 사용자로 컨테이너를 실행합니다. root로 실행하면 컨테이너가 탈취당했을 때 호스트까지 침해될 위험이 있습니다.
.dockerignore 파일은 node_modules, .git, 테스트 파일 등 이미지에 불필요한 파일을 명시하여 COPY . . 시 제외되도록 합니다.
이는 빌드 컨텍스트 크기를 줄여 Docker 데몬으로 전송되는 데이터량을 감소시키고 빌드 속도를 높입니다. 여러분이 이 최적화 기법들을 사용하면 Node.js 애플리케이션 이미지를 1GB에서 100MB 이하로, Go 애플리케이션은 10MB 이하로 줄일 수 있습니다.
CI/CD 파이프라인에서 이미지 푸시와 풀 시간이 크게 단축되어 배포 속도가 빨라지며, Kubernetes 환경에서 새 Pod 시작 시간도 짧아져 스케일링이 더 빠르게 일어납니다. 또한 이미지에 불필요한 도구가 없어 공격자가 컨테이너 내부에서 악용할 수 있는 수단이 줄어들어 보안이 강화됩니다.
컨테이너 레지스트리 저장 비용과 네트워크 전송 비용도 절감됩니다.
실전 팁
💡 docker build --target builder로 특정 스테이지만 빌드할 수 있습니다. 개발 환경에서 빌드 도구가 필요할 때 유용합니다.
💡 Alpine 이미지는 작지만 musl libc를 사용하여 일부 바이너리와 호환되지 않을 수 있습니다. 문제 발생 시 debian:slim을 고려하세요.
💡 docker image history my-image로 각 레이어 크기를 확인하고, dive 도구로 이미지를 분석하여 어떤 파일이 공간을 차지하는지 파악하세요.
💡 패키지 매니저 캐시를 삭제하세요. RUN apt-get update && apt-get install -y pkg && rm -rf /var/lib/apt/lists/*처럼 한 레이어에서 정리하세요.
💡 COPY는 가장 자주 변경되는 파일(소스 코드)을 마지막에 복사하여 의존성 레이어가 캐시되도록 순서를 최적화하세요.
10. 컨테이너 헬스체크와 재시작 정책 - 안정성과 자동 복구
시작하며
여러분의 컨테이너가 실행 중(running)으로 표시되지만 실제로는 애플리케이션이 응답하지 않거나 데드락 상태에 빠져서 요청을 처리하지 못하는 상황을 겪어본 적 있나요? 데이터베이스 연결 실패나 메모리 부족으로 컨테이너가 종료되었는데, 수동으로 다시 시작해야 하는 번거로움을 느낀 적이 있나요?
컨테이너의 "실행 중" 상태가 반드시 "정상 작동"을 의미하지는 않습니다. 프로세스는 살아있지만 애플리케이션은 죽어있을 수 있습니다.
이런 상황을 감지하고 자동으로 복구하는 메커니즘이 없다면, 장애가 발생해도 알아채지 못하거나 수동 개입이 필요하여 운영 부담이 커집니다. Docker의 헬스체크와 재시작 정책이 바로 이 문제의 해결책입니다.
헬스체크는 컨테이너가 실제로 정상 작동하는지 주기적으로 확인하고, 재시작 정책은 실패 시 자동으로 복구를 시도합니다. 이를 통해 자가 치유(Self-Healing) 시스템을 구축할 수 있습니다.
개요
간단히 말해서, 헬스체크는 컨테이너 내부 애플리케이션의 실제 건강 상태를 주기적으로 검사하는 메커니즘이고, 재시작 정책은 컨테이너 실패 시 자동으로 재시작하는 규칙으로, 함께 사용하면 안정적인 자동 복구 시스템을 만들 수 있습니다. 헬스체크는 Dockerfile의 HEALTHCHECK 명령이나 docker run의 --health-cmd 옵션으로 정의합니다.
Docker는 지정된 간격으로 명령을 실행하여 성공 여부를 판단하며, 연속 실패 횟수가 임계값을 넘으면 컨테이너를 "unhealthy" 상태로 표시합니다. 예를 들어, 웹 서버는 HTTP 엔드포인트를 curl로 확인하고, 데이터베이스는 간단한 쿼리를 실행하여 응답성을 검증할 수 있습니다.
Kubernetes나 Docker Swarm 같은 오케스트레이터는 unhealthy 컨테이너를 자동으로 재시작하거나 교체합니다. 재시작 정책은 --restart 옵션으로 지정하며, no(재시작 안 함), on-failure(오류 종료 시만), always(항상 재시작), unless-stopped(명시적 중지 전까지) 중 선택할 수 있습니다.
예를 들어, 프로덕션 웹 서버는 always 정책으로 어떤 이유로 종료되든 자동으로 재시작하고, 일회성 데이터 마이그레이션 작업은 no 정책으로 한 번만 실행하도록 설정합니다. 기존에는 모니터링 도구가 장애를 감지하면 알람을 보내고 엔지니어가 수동으로 개입했다면, 이제는 Docker가 자동으로 문제를 감지하고 복구를 시도하여 다운타임을 최소화할 수 있습니다.
헬스체크와 재시작 정책의 핵심 특징은 첫째, 자동 복구(Self-Healing)입니다. 인간 개입 없이 일시적 장애를 극복합니다.
둘째, 조기 감지입니다. 완전한 장애가 되기 전에 문제를 발견합니다.
셋째, 오케스트레이션 통합입니다. Kubernetes 같은 시스템이 헬스체크 결과를 기반으로 의사결정을 합니다.
넷째, 다운타임 최소화입니다. 빠른 자동 복구로 서비스 가용성을 높입니다.
이러한 특징들이 신뢰할 수 있는 프로덕션 환경의 기반이 됩니다.
코드 예제
# Dockerfile에 헬스체크 정의 - 웹 애플리케이션 예제
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
# 30초마다 /health 엔드포인트 확인, 3초 타임아웃
# 3번 연속 실패하면 unhealthy로 표시
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
CMD ["node", "server.js"]
# 재시작 정책과 함께 컨테이너 실행
docker run -d \
--name web-app \
--restart unless-stopped \
--health-cmd="wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1" \
--health-interval=30s \
--health-timeout=3s \
--health-retries=3 \
-p 3000:3000 \
my-web-app:latest
# 헬스체크 상태 확인
docker inspect --format='{{.State.Health.Status}}' web-app
# Docker Compose에서 헬스체크 정의
# services:
# web:
# image: my-web-app
# healthcheck:
# test: ["CMD", "wget", "--spider", "http://localhost:3000/health"]
# interval: 30s
# timeout: 3s
# retries: 3
# start_period: 40s
# restart: unless-stopped
설명
이것이 하는 일: 헬스체크와 재시작 정책은 컨테이너의 건강을 모니터링하고 문제 발생 시 자동으로 복구하여, 인간 개입 없이 시스템 안정성을 유지합니다. 첫 번째로, HEALTHCHECK 명령은 여러 옵션을 가집니다.
--interval=30s는 30초마다 헬스체크를 실행하고, --timeout=3s는 명령이 3초 내에 완료되지 않으면 실패로 간주합니다. --start-period=40s는 컨테이너 시작 후 40초 동안은 실패를 카운트하지 않는 유예 기간으로, 애플리케이션 초기화 시간을 고려합니다.
--retries=3은 3번 연속 실패해야 unhealthy로 표시한다는 의미로, 일시적 네트워크 지연 같은 거짓 양성을 방지합니다. 이렇게 하는 이유는 단일 실패로 즉시 컨테이너를 재시작하면 불필요한 재시작이 반복될 수 있기 때문입니다.
그 다음으로, 헬스체크 명령 자체는 wget --spider로 HTTP 엔드포인트를 확인합니다. --spider는 파일을 다운로드하지 않고 존재만 확인하는 옵션으로 가볍습니다.
|| exit 1은 wget이 실패하면 종료 코드 1을 반환하여 Docker에게 실패를 알립니다. 종료 코드 0은 성공, 1은 unhealthy, 2는 reserved로 구분됩니다.
애플리케이션은 /health 엔드포인트를 구현하여 데이터베이스 연결, 외부 API 접근성 등 핵심 의존성을 확인하고 200 OK를 반환해야 합니다. --restart unless-stopped 정책은 컨테이너가 종료되면 자동으로 재시작하지만, 사용자가 명시적으로 중지(docker stop)한 경우는 재시작하지 않습니다.
이는 프로덕션 환경에서 가장 권장되는 정책으로, 호스트가 재부팅되어도 컨테이너가 자동으로 시작되며, 의도적 중지는 유지됩니다. always 정책은 명시적 중지 후에도 재시작하므로 주의해서 사용해야 합니다.
docker inspect 명령으로 현재 헬스체크 상태를 확인할 수 있으며, starting, healthy, unhealthy 중 하나를 반환합니다. 여러분이 헬스체크와 재시작 정책을 적절히 구성하면 데이터베이스 연결이 일시적으로 끊겼을 때 애플리케이션이 자동으로 재시작되어 연결을 복구할 수 있습니다.
메모리 누수로 애플리케이션이 느려지면 헬스체크가 타임아웃을 감지하여 컨테이너를 재시작합니다. Kubernetes 환경에서는 헬스체크 실패 시 새로운 Pod을 생성하고 트래픽을 전환하여 무중단 복구가 가능합니다.
이러한 자동화로 새벽 3시에 장애 알람으로 깨어나는 일을 줄이고, 시스템 가용성을 크게 향상시킬 수 있습니다.
실전 팁
💡 헬스체크 엔드포인트는 가볍게 유지하세요. 복잡한 비즈니스 로직이 아니라 핵심 의존성만 빠르게 확인해야 합니다. 목표는 3초 이내 응답입니다.
💡 start-period를 애플리케이션 초기화 시간보다 길게 설정하세요. 그렇지 않으면 정상 시작 중인 컨테이너가 unhealthy로 표시됩니다.
�� 로컬 개발에서는 --restart no를 사용하세요. 코드 오류로 컨테이너가 무한 재시작되는 것을 방지합니다.
💡 헬스체크 실패 로그를 확인하여 문제 원인을 파악하세요. docker inspect로 최근 헬스체크 출력을 볼 수 있습니다.
💡 데이터베이스 같은 스테이트풀 서비스는 재시작 전에 데이터 일관성을 확인하는 로직을 포함하세요. 단순 재시작이 문제를 악화시킬 수 있습니다.