본문으로 건너뛰기

Docker 런타임 등록

KIWI 플랫폼에 Docker 또는 Podman 런타임을 연결하여 컨테이너를 관리할 수 있습니다. 런타임을 등록하면 웹 UI에서 컨테이너를 손쉽게 관리할 수 있습니다.

런타임 환경 페이지

왜 Docker 런타임을 등록하나요?​

Docker 런타임을 등록하면 터미널 명령어 없이도 웹 UI에서 다양한 작업을 수행할 수 있습니다:

  • 컨테이너 상태를 한눈에 확인
  • 클릭 한 번으로 컨테이너 시작/중지/재시작
  • 실시간 로그 확인 및 문제 추적
  • 컨테이너 내부로 Shell 접속
Docker vs Podman

Docker와 Podman은 모두 컨테이너를 실행하는 런타임입니다. Podman은 Docker와 호환되면서도 데몬 없이 실행되어 보안이 더 강화된 대안입니다. KIWI는 두 가지 모두 지원합니다.

사전 요구사항​

런타임을 등록하기 전에 다음 조건이 충족되어야 합니다:

  • 대상 장비가 KIWI에 먼저 등록되어 있어야 합니다 .
    • 아직 등록하지 않으셨다면 장비 등록 가이드를 먼저 진행하세요
  • 해당 장비에 Docker 또는 Podman이 설치되어 있어야 합니다 .
  • SSH로 접속하는 계정이 docker 명령을 실행할 수 있는 권한을 가지고 있어야 합니다 .
Docker 설치 여부 확인하기

서버에 SSH로 접속한 후 다음 명령으로 Docker가 설치되어 있는지 확인할 수 있습니다:

docker --version

버전 정보가 출력되면 Docker가 설치되어 있는 것입니다.

등록 절차​

Step 1: 런타임 환경 페이지 이동​

  1. 좌측 메뉴에서 [런타임 환경] 페이지를 클릭합니다 .
  2. 상단의 Docker 런타임 추가 버튼을 클릭합니다 .

Step 2: 런타임 정보 입력​

런타임 등록 모달에서 다음 정보를 입력합니다:

  • 이름: 런타임을 구분할 수 있는 식별명입니다 .

    • 예: dev-docker, prod-container-host
    • 환경(dev/prod)과 용도를 포함하면 관리가 편합니다 .

  • 장비: Docker가 설치된 장비를 선택합니다 .

    • 드롭다운에 등록된 장비 목록이 표시됩니다 .
    • 원하는 장비가 없다면 먼저 장비 등록을 진행하세요

  • 타입: 설치된 런타임 종류를 선택합니다 .

  • Docker: 가장 널리 사용되는 컨테이너 런타임입니다. 일반적인 환경에 적합합니다.

  • Podman: 데몬 없이 동작하는 보안 강화 런타임입니다. 보안이 중요한 환경에 권장됩니다.

Step 3: 연결 테스트​

  1. 테스트 연결 버튼을 클릭합니다 .
  2. 연결이 성공하면 Docker 버전 정보가 표시됩니다:
Docker version 24.0.7
버전 정보가 보이면 성공입니다

버전 정보가 표시되면 KIWI가 해당 서버의 Docker와 정상적으로 통신할 수 있다는 의미입니다.

Step 4: 저장​

연결 테스트가 성공하면 저장 버튼을 클릭하여 런타임을 등록합니다.

런타임 기능​

등록된 Docker 런타임에서는 다음 기능을 사용할 수 있습니다:

  • 이미지 목록: 해당 호스트에 저장된 Docker 이미지 목록을 조회합니다 .
  • 컨테이너 관리: 실행 중인 컨테이너를 시작, 중지, 재시작할 수 있습니다 .
  • 로그 조회: 컨테이너의 실시간 로그를 확인합니다 .
  • Shell 접속: 컨테이너 내부에 접속하여 명령을 실행합니다 .
로그 조회 활용하기

컨테이너에 문제가 생겼을 때 로그 조회 기능을 사용하면 터미널 접속 없이 바로 원인을 파악할 수 있습니다. 실시간 로그 스트리밍도 지원됩니다.

문제 해결​

Docker 접근 불가 (permission denied)​

permission denied while trying to connect to Docker

원인: SSH 사용자가 Docker 소켓에 접근할 권한이 없습니다.

해결 방법:

  1. docker 그룹에 사용자 추가
sudo usermod -aG docker $USER
  1. 변경사항 적용 (둘 중 하나 선택)
# 방법 1: 현재 세션에서 바로 적용
newgrp docker

# 방법 2: 로그아웃 후 다시 로그인
  1. 권한이 적용되었는지 확인
docker ps
보안 참고사항

docker 그룹에 사용자를 추가하면 해당 사용자는 루트 수준의 권한을 얻게 됩니다. 운영 환경에서는 꼭 필요한 사용자에게만 권한을 부여하세요.

Docker 미설치 (command not found)​

docker: command not found

원인: 대상 서버에 Docker가 설치되어 있지 않습니다.

해결 방법:

# Docker 공식 설치 스크립트 (Ubuntu/Debian/CentOS)
curl -fsSL https://get.docker.com | sh

# 설치 후 Docker 서비스 시작
sudo systemctl start docker

# 부팅 시 자동 시작 설정
sudo systemctl enable docker

# 설치 확인
docker --version

다음 단계​

Docker 런타임 등록이 완료되었습니다! 이제 서비스를 등록하고 배포할 준비가 되었습니다: