Docker 배포
빌드된 컨테이너 이미지를 Docker 또는 Podman 런타임에 배포하는 방법을 안내합니다. Docker 배포는 설정이 간단하고 빠르게 시작할 수 있어 개발 환경이나 소규모 서비스에 적합합니다.
Docker 배포
- 복잡도: 간단함
- 확장성: 제한적
- 고가용성: 수동 구성 필요
- 추천 환경: 개발, 테스트, 소규모
Kubernetes 배포
- 복잡도: 복잡함
- 확장성: 자동 확장 지원
- 고가용성: 기본 지원
- 추천 환경: 스테이징, 프로덕션
사전 요구사항
배포를 시작하기 전에 다음을 확인하세요:
- Docker/Podman 런타임 등록: [런타임 환경] 페이지에 Docker 또는 Podman 런타임이 등록되어 있어야 합니다.
- 이미지 빌드 완료: 이미지가 레지스트리에 푸시되어 있어야 합니다.
Step 1: Deploy 단계로 이동
- [서비스 관리] 페이지로 이동합니다.
- 배포할 서비스를 선택합니다.
- 파이프라인에서 Deploy 단계를 클릭합니다.
Step 2: Docker 배포 선택
- 배포 유형에서 Docker를 선택합니다.
- 배포 대상 런타임을 선택합니다:
- Docker: Docker Engine 기반입니다. 가장 일반적이며 넓은 호환성을 가집니다.
- Podman: Rootless 컨테이너 런타임입니다. 보안이 강화되어 있고 데몬 없이 동작합니다.
Podman은 Docker와 호환되는 컨테이너 런타임이지만 데몬 없이 동작하며 rootless 모드를 지원합니다. 보안이 중요한 환경에서 권장됩니다.
Step 3: 컨테이너 기본 설정
컨테이너의 기본 정보를 입력합니다:
- 컨테이너 이름: 컨테이너 식별 이름 (예:
my-web-app) - 이미지 태그: 배포할 이미지 (예:
harbor.company.com/library/app:latest) - 재시작 정책: 컨테이너 재시작 규칙 (예:
always)
재시작 정책 이해하기
- no: 재시작하지 않습니다. 일회성 작업에 추천합니다.
- on-failure: 오류로 종료 시에만 재시작합니다. 개발 환경에 추천합니다.
- always: 항상 재시작합니다 (수동 중지 포함). 테스트 환경에 추천합니다.
- unless-stopped: 수동 중지 전까지 재시작합니다. 프로덕션에 권장합니다.
프로덕션 환경에서는 unless-stopped를 권장합니다. 시스템 재부팅 시에도 컨테이너가 자동으로 시작되지만, 의도적으로 중지한 경우는 재시작되지 않습니다.
Step 4: 포트 매핑
외부에서 컨테이너에 접근할 수 있도록 포트를 매핑합니다.
- 호스트 포트: 외부 접근 포트 (예:
8080) - 컨테이너 포트: 컨테이너 내부 포트 (예:
80) - 프로토콜: TCP 또는 UDP (기본:
tcp)
다중 포트 매핑
여러 포트를 매핑해야 하는 경우:
8080:80 # HTTP 트래픽
8443:443 # HTTPS 트래픽
9090:9090 # 메트릭 엔드포인트
호스트의 동일한 포트에 여러 컨테이너를 바인딩할 수 없습니다. 포트가 이미 사용 중이면 다른 포트를 선택하세요.
Step 5: 볼륨 마운트 (선택사항)
데이터를 영속적으로 저장하거나 호스트와 파일을 공유하려면 볼륨을 마운트합니다.
5.1 바인드 마운트
호스트의 특정 디렉토리를 컨테이너에 마운트합니다:
- 호스트 경로: 호스트의 디렉토리 (예:
/data/app) - 컨테이너 경로: 컨테이너 내 마운트 위치 (예:
/app/data) - 읽기 전용: 읽기만 허용할지 여부 (체크 시
:ro)
5.2 Docker 볼륨 사용
Docker가 관리하는 볼륨을 사용합니다:
- 볼륨 이름: Docker 볼륨 이름 (예:
app-data) - 컨테이너 경로: 마운트 위치 (예:
/app/data)
- 바인드 마운트: 호스트의 특정 경로를 직접 마운트. 설정 파일이나 로그 확인 시 유용
- Docker 볼륨: Docker가 관리하는 볼륨. 데이터베이스 등 영속 데이터에 권장
Step 6: 환경 변수 설정
애플리케이션에 필요한 환경 변수를 설정합니다.
직접 입력
키-값 쌍으로 환경 변수를 입력합니다:
NODE_ENV: 실행 환경을 지정합니다 (예:production)DATABASE_URL: DB 연결 문자열을 지정합니다 (예:postgresql://...)API_KEY: 외부 API 키를 지정합니다 (예:xxx-xxx-xxx)
환경 파일 (.env)
.env 파일을 참조하여 환경 변수를 일괄 로드할 수 있습니다.
비밀번호나 API 키 같은 민감한 정보는 환경 변수로 전달하되, 소스 코드에 하드코딩하지 마세요. .env 파일은 .gitignore에 추가하여 버전 관리에서 제외하세요.
Step 7: 네트워크 설정 (선택사항)
컨테이너 간 통신이나 네트워크 격리가 필요한 경우 설정합니다.
- 네트워크 이름: Docker 네트워크 (예:
app-network) - 네트워크 모드: 네트워크 유형 (기본:
bridge) - 호스트명: 컨테이너 호스트명 (예:
api-server)
- bridge: 기본 모드. 컨테이너가 격리된 네트워크에서 실행
- host: 호스트 네트워크를 직접 사용. 포트 매핑 불필요
- none: 네트워크 비활성화
Step 8: 배포 실행
- 모든 설정을 검토합니다.
- 배포 버튼을 클릭합니다.
- 배포 상태를 확인합니다.
배포 과정
[1/4] Pulling image...
[2/4] Stopping existing container...
[3/4] Creating new container...
[4/4] Starting container...
Container started successfully!
동일한 이름의 컨테이너가 이미 실행 중이면 자동으로 중지하고 새 컨테이너로 교체합니다.
Step 9: 컨테이너 상태 확인
Operate 단계에서 컨테이너 상태를 확인합니다.
Docker Containers 탭
다음 정보를 확인할 수 있습니다:
- 상태: Running / Stopped / Error
- 포트: 매핑된 포트 정보
- 생성 시간: 컨테이너 생성 시점
- 리소스: CPU / Memory 사용량
컨테이너 제어
- Start: 중지된 컨테이너를 시작합니다.
- Stop: 실행 중인 컨테이너를 중지합니다.
- Restart: 컨테이너를 재시작합니다.
- Remove: 컨테이너를 삭제합니다.
Docker Compose 배포
여러 컨테이너를 함께 배포해야 하는 경우 Docker Compose를 사용할 수 있습니다.
Compose 파일 설정
서비스 설정에서 Docker Compose 파일 경로를 등록합니다:
- Compose 파일: docker-compose.yml 경로 (예:
./docker-compose.yml) - 환경 파일: .env 파일 경로 (예:
./.env.production)
Compose 배포
- Compose 파일이 설정된 서비스의 Deploy 단계 클릭
- 자동으로 Compose 모드로 전환됩니다.
docker-compose up -d명령이 실행되어 전체 스택이 배포됩니다.
- 여러 컨테이너를 하나의 명령으로 관리
- 컨테이너 간 의존성 정의 가능 (
depends_on) - 네트워크 자동 생성
문제 해결
컨테이너 시작 실패
- 포트 충돌: 다른 포트를 사용하거나 기존 컨테이너를 중지합니다.
- 이미지 없음: 이미지 태그를 확인하고
docker pull을 실행합니다. - 권한 문제: 볼륨 마운트 경로의 권한을 확인합니다.
컨테이너 크래시 (재시작 반복)
- 환경 변수 누락: 필수 환경 변수가 설정되었는지 확인합니다.
- 의존성 문제:
docker logs명령으로 오류 메시지를 확인합니다. - 메모리 부족: 리소스 제한을 증가시키거나 애플리케이션을 최적화합니다.
외부에서 접근 불가
- 포트 미매핑: 포트 매핑 설정을 확인합니다.
- 방화벽 차단: 호스트 방화벽에서 포트를 허용합니다.
- 컨테이너 내부 오류: 로그를 확인하고 애플리케이션 상태를 점검합니다.
Operate 단계의 Logs 탭에서 실시간 로그를 확인하거나, 터미널에서 docker logs <container-name> 명령을 사용하세요.