Docker 배포
빌드된 컨테이너 이미지를 Docker 또는 Podman 런타임에 배포하는 방법을 안내합니다. KIOPS의 Docker 배포는 docker-compose 기반으로 동작하며, 단일 서비스부터 여러 컨테이너가 결합된 멀티 서비스 스택까지 동일한 흐름으로 배포할 수 있습니다.
왜 이 가이드를 읽어야 하는가
이 가이드를 따라가면 K8s 클러스터 없이도 단일 서버에 docker-compose 기반으로 서비스를 배포하고, 배포 직전 자동 백업으로 안전망을 확보할 수 있습니다. 비개발 운영팀은 "이미지 버전 선택 → 자동 백업 확인 → 배포 버튼" 3단계만 따라가면 되며, 세부 설정이 필요할 때만 docker-compose 편집 모드를 사용합니다.
Docker 배포
- 복잡도: 간단함
- 확장성: 제한적
- 고가용성: 수동 구성 필요
- 추천 환경: 개발, 테스트, 소규모
Kubernetes 배포
- 복잡도: 복잡함
- 확장성: 자동 확장 지원
- 고가용성: 기본 지원
- 추천 환경: 스테이징, 프로덕션
시작하기 전에: 알아둘 용어
본문에 들어가기 전에 자주 등장하는 용어를 한 줄씩 정리합니다. 본문에서 처음 등장할 때 "(용어 사전 참고)" 안내를 함께 표시합니다.
| 용어 | 정의 + 일상 비유 |
|---|---|
| 컨테이너 | 앱 하나를 격리해서 실행하는 격리 박스. 도시락 한 칸처럼 안의 음식(앱)은 옆 칸과 섞이지 않습니다. |
| 이미지 | 컨테이너를 만들기 위한 스냅샷(틀). 붕어빵 틀과 같습니다. 같은 틀로 여러 개를 찍어낼 수 있습니다. |
| Docker Compose | 여러 컨테이너의 실행 정의를 한 YAML 파일로 묶어 한 번에 띄우는 도구. 여러 가전제품을 하나의 멀티탭에 연결해 한 번에 켜는 것과 비슷합니다. |
| 볼륨 | 컨테이너 재시작 후에도 유지되는 데이터 저장 공간. 외장 하드처럼 컨테이너가 사라져도 안의 파일은 살아남습니다. |
| 환경 변수 | 컨테이너 실행 시 주입되는 설정값(예: DATABASE_URL). 요리할 때 마지막에 추가하는 양념과 같습니다. 같은 코드라도 양념(환경 변수)에 따라 동작이 달라집니다. |
| 자동 백업 | 배포 직전 현재 컨테이너/볼륨 상태를 보관하는 KIOPS 기능. 공사 시작 전에 찍어두는 비포 사진과 같습니다. 문제가 생기면 그 상태로 되돌릴 수 있습니다. |
사전 요구사항
배포를 시작하기 전에 다음을 확인하세요:
- Docker/Podman 런타임 등록: [런타임 환경] 페이지에 Docker 또는 Podman 런타임이 등록되어 있어야 합니다.
- 이미지 빌드 완료: 배포할 이미지가 레지스트리에 푸시되어 있어야 합니다.
- docker-compose.yml 정의: 서비스의 배포 구성은 docker-compose.yml에서 관리됩니다. 단일 컨테이너든 멀티 컨테이너든 동일하게 적용됩니다.
Step 1: Deploy 단계로 이동
- [서비스 관리] 페이지로 이동합니다.
- 배포할 서비스를 선택합니다.
- 파이프라인에서 Deploy 단계를 클릭합니다.
Step 2: Docker 배포 선택
- 배포 유형에서 Docker를 선택합니다.
- 배포 대상 런타임을 선택합니다.
- Docker: Docker Engine 기반입니다. 가장 일반적이며 넓은 호환성을 가집니다.
- Podman: Rootless 컨테이너 런타임입니다. 보안이 강화되어 있고 데몬 없이 동작합니다.
Podman은 Docker와 호환되는 컨테이너 런타임이지만 데몬 없이 동작하며 rootless 모드를 지원합니다. 보안이 중요한 환경에서 권장됩니다.
Step 3: 배포 옵션 입력
Docker 배포 모달에서는 다음 항목만 입력합니다. 실제 UI 라벨은 이미지 버전이며, 본 문서에서는 의미를 명확히 하기 위해 이미지 태그/버전을 혼용합니다. (이미지, 자동 백업 참고)
| 옵션 | 설명 |
|---|---|
| 이미지 버전 | 배포할 컨테이너 이미지의 태그(버전)를 선택합니다. 빌드 이력에 등록된 이미지 목록에서 선택하거나 직접 입력할 수 있습니다. |
| 배포 전 자동 백업 | 기본값 켜짐(ON) 상태이며, 배포 직전에 현재 컨테이너/볼륨의 백업을 자동으로 생성합니다. 배포 실패 시 이전 상태로 복원할 수 있어 운영 환경에서 권장됩니다. |
자동 백업은 [백업 관리] 에 등록된 외부 저장소(오브젝트 스토리지 등)를 사용합니다. 외부 저장소가 등록돼 있지 않거나 인증이 만료된 상태에서 배포를 실행하면 백업 단계에서 실패하고 배포가 중단됩니다. 첫 배포 전에 한 번은 백업 시스템 가이드를 따라 저장소 연결을 확인하세요. 외부 저장소가 아직 없다면 자동 백업 옵션을 OFF로 두고 배포한 뒤, 저장소 연결 후 다시 ON 으로 전환해도 됩니다.
이미지 버전에 latest 를 사용하면 배포 시점마다 다른 이미지가 내려오면서 롤백 기준이 사라지고, 같은 시점이라도 두 노드가 서로 다른 이미지를 받는 사태가 생길 수 있습니다. 운영 환경에서는 빌드 ID/커밋 해시가 포함된 고정 태그(예: main-abc123, v1.2.3)를 사용하세요.
DockerDeployModal에서는 위의 두 항목만 입력하면 됩니다. 컨테이너 이름, 포트 매핑, 볼륨 마운트, 환경 변수, 네트워크 설정 등 모든 세부 설정은 docker-compose.yml 편집 모드(ComposeDeployEditMode) 에서 처리됩니다. 자세한 내용은 docker-compose.yml 편집을 참고하세요.
Step 4: 배포 실행
- 이미지 버전과 자동 백업 옵션을 검토합니다.
- 배포 버튼을 클릭합니다.
- 백엔드가
docker-compose pull및docker-compose up -d를 실행하여 스택을 갱신합니다. - 배포 진행 로그가 실시간으로 표시됩니다.
서비스가 멀티 서비스(is_multi_service)로 등록된 경우, docker-compose.yml의 여러 서비스가 한 번의 배포로 함께 갱신됩니다. 단일 서비스든 멀티 서비스든 사용 흐름은 동일합니다.
docker-compose.yml 편집
컨테이너 이름, 포트 매핑, 볼륨, 환경 변수, 네트워크 등 모든 세부 설정은 docker-compose.yml에서 관리됩니다. KIOPS의 Compose 편집 모드에서 직접 편집할 수 있습니다. (Docker Compose, 볼륨, 환경 변수 참고)
docker-compose.yml은 YAML 문법을 사용하므로 들여쓰기는 공백 2칸, 탭 키 금지입니다. 한 칸이라도 어긋나거나 탭이 섞이면 yaml: line N: did not find expected key 같은 오류로 배포 전체가 실패합니다. KIOPS의 Compose 편집기는 들여쓰기 오류를 미리 표시해 주므로 저장 전 빨간 줄이 없는지 확인하세요.
편집 가능한 항목
services:
api:
image: harbor.company.com/library/app:latest
container_name: my-web-app
restart: unless-stopped
ports:
- "8080:80"
- "8443:443"
volumes:
- app-data:/app/data
- ./config:/app/config:ro
environment:
NODE_ENV: production
DATABASE_URL: ${DATABASE_URL}
networks:
- app-network
networks:
app-network:
driver: bridge
volumes:
app-data:
| 항목 | docker-compose 키 |
|---|---|
| 컨테이너 이름 | container_name |
| 재시작 정책 | restart (no / on-failure / always / unless-stopped) |
| 포트 매핑 | ports |
| 볼륨 마운트 | volumes |
| 환경 변수 | environment 또는 env_file |
| 네트워크 설정 | networks |
비밀번호나 API 키 같은 민감 정보는 docker-compose.yml에 평문으로 입력하지 말고, .env 파일이나 Secret으로 분리하세요.
Step 5: 컨테이너 상태 확인
운영 모달에서 컨테이너 상태를 확인합니다. Docker 운영 모달은 개요 / 컨테이너 목록 / 배포 관리 / 로그 조회 / 명령 실행 / 도메인 설정 탭으로 구성됩니다(로그 조회·명령 실행 탭은 해당 권한이 있을 때만 표시됩니다). 도메인 대상 DAST 스캔은 [보안 분석] 페이지로 이관되어 운영 모달에는 더 이상 없습니다.
- [서비스 관리] 페이지에서 서비스의 운영 카드를 클릭합니다.
- 운영 모달에서 컨테이너 목록 탭을 선택하면 다음 정보를 확인할 수 있습니다.
- 상태: Running / Stopped / Error
- 포트: 매핑된 포트 정보
- 생성 시간: 컨테이너 생성 시점
- 리소스: CPU / Memory 사용량
컨테이너 제어
운영 모달의 배포 관리 탭에서 docker-compose 기반의 재배포, 중지, 시작 작업을 수행할 수 있습니다.
문제 해결
컨테이너 시작 실패
- 포트 충돌: docker-compose.yml에서 호스트 포트를 다른 값으로 변경합니다.
- 이미지 없음: 레지스트리에 해당 태그가 존재하는지, 인증 정보가 올바른지 확인합니다.
- 권한 문제: 볼륨 마운트 경로의 권한을 확인합니다.
컨테이너 크래시 (재시작 반복)
- 환경 변수 누락: 필수 환경 변수가 설정되었는지 확인합니다.
- 의존성 문제: 로그에서 오류 메시지를 확인합니다.
- 메모리 부족: 리소스 제한을 조정하거나 애플리케이션을 최적화합니다.
외부에서 접근 불가
- 포트 미매핑: docker-compose.yml의
ports설정을 확인합니다. - 방화벽 차단: 호스트 방화벽에서 해당 포트를 허용합니다.
- 컨테이너 내부 오류: 로그를 확인하고 애플리케이션 상태를 점검합니다.
운영 모달의 로그 조회 탭에서 실시간 로그를 확인할 수 있습니다.
다음에 할 일
Docker 배포가 정상적으로 완료됐다면, 다음 동선을 권장합니다.
- 자동 백업 설정 점검: 첫 배포 후에는 [백업 관리] 페이지에서 백업이 실제로 생성됐는지, 외부 저장소(오브젝트 스토리지)에 올라갔는지 확인합니다.
- compose 편집 가이드 익히기: 컨테이너 이름·포트·볼륨 같은 세부 설정은 compose 편집 모드에서 처리합니다. 자주 쓰는 옵션을 미리 한 번 살펴보세요.
- 운영 모달 활용: 운영 모달의 로그 조회 / 명령 실행 / 배포 관리 탭으로 컨테이너 상태를 점검하고 문제 발생 시 빠르게 대응할 수 있도록 익혀두세요.