11화. Komodo — 30개 컨테이너 업데이트를 버튼 한 번에 (배포 자동화)

서비스가 열 개를 넘어서면 업데이트가 일이 된다. 각 서비스의 최신 이미지 확인 → compose pull → 재시작 → 로그 확인을 열 번 반복해야 한다. 더 큰 문제는 "누가, 언제, 무엇을 업데이트했나"가 아무 기록에도 남지 않는다는 것. Komodo는 이 업데이트 운영 전체를 관리하고 자동화하는 배포 오케스트레이션 도구다. 10화의 Portainer가 "보고 조작하는 콘솔"이라면, Komodo는 "업데이트 절차를 시스템화하는 도구"다.

이런 때 유용합니다

• 컨테이너가 열 개를 넘어서 수동 업데이트가 무리일 때. 스택별 업데이트 상태가 한 화면에 모이고, 배포는 버튼이다.
• 업데이트 후 문제가 생겨 되돌려야 할 때. 이전 이미지 태그로 재배포하는 롤백이 기능이다.
• compose 파일이 서버 밖(git)에 있고 싶을 때. 저장소의 compose 파일이 곧 배포 기준이 되는 "sync" 구조를 지원한다 — 서버에서 직접 파일을 고치는 실수가 원천 차단된다.
• 새 이미지가 나왔을 때 알림을 받고 싶을 때. 업데이트 가능 상태를 감지해 알려준다.
• 누가 언제 무엇을 배포했는지 남아야 할 때. 배포 이력이 기록된다.

필요한 것은 도커와, 진짜 힘을 내려면 compose 파일을 올려둘 git 저장소 하나다.

Komodo는 어떤 프로그램인가

Komodo는 도커 컴포즈 스택의 배포와 업데이트를 중앙에서 관리하는 오픈소스 오케스트레이션 도구다. 구조는 아주 단순하다.

• Core: 웹UI와 API를 제공하는 두뇌. 서버·스택·배포·알림을 관리한다.
• Periphery: 관리할 각 서버에 설치하는 에이전트. Core의 명령을 받아 그 서버의 도커를 실제로 조작한다.

즉 서버가 여러 대여도 에이전트만 설치하면 한 화면에서 전부 관리할 수 있다. 서버 한 대 환경이라면 Core와 Periphery를 같은 서버에 두면 된다.

전체 구성

flowchart LR
    GIT["git 저장소 - compose 파일 관리"] -->|리소스 싱크| CORE
    A["운영자 - 배포·승인"] --> CORE
    subgraph SRV["Docker 서버"]
        P["Periphery 에이전트"]
        DK["Docker 엔진"]
        DK --> S1["스택들"]
    end
    subgraph COREC["Komodo Core"]
        CORE["웹UI · API · 이력"]
        AL["알림 - 텔레그램·디스코드"]
    end
    CORE -->|명령| P
    P --> DK
    CORE --> AL
    AL --> A

설치 방법

1단계 — Core와 에이전트

공식 문서(komo.do)가 설치용 compose를 제공한다. 구성의 뼈대는 이렇다:

services:
  komodo-core:
    image: ghcr.io/moghtech/komodo-core:latest
    ports:
      - "9120:9120"          # 웹UI
    volumes:
      - /opt/docker/komodo/db:/db
  komodo-mongo:
    image: mongo:7
    volumes:
      - /opt/docker/komodo/mongo:/data/db
  komodo-periphery:
    image: ghcr.io/moghtech/komodo-periphery:latest
    ports:
      - "8120:8120"
    volumes:
      - /opt/docker/periphery:/etc/periphery   # 에이전트 설정
      - /var/run/docker.sock:/var/run/docker.sock
      - /opt/docker:/opt/docker                # 스택 파일이 있는 위치

• Core는 웹UI에서 초기 관리자 계정을 만들고, 서버 등록용 API 키를 발급한다.
• Periphery는 발급받은 키로 Core를 향하도록 설정 파일을 작성한다(공식 문서의 periphery config 참조).
• Periphery 설정에서 스택 파일들이 있는 경로를 열어주는 것이 핵심이다 — 그 경로의 compose 파일들을 Komodo가 배포 대상으로 인식한다.

2단계 — git 저장소와 싱크

compose 파일들을 git 저장소에 올리고(비공개 저장소 권장), Komodo에서 리소스 싱크를 구성한다. 이후로는 "저장소의 파일을 수정하고 push → Komodo에서 배포"가 유일한 변경 절차가 된다. 서버에서 직접 고친 설정은 git과 어긋나 혼란을 부르므로 금지 규칙으로 박제하자.

3단계 — 알림 연결

텔레그램·디스코드 등을 연결해두면 "새 이미지 있음", "배포 성공/실패"가 폰으로 온다. 배포 이력과 알림이 같이 있으면 문제 추적이 빨라진다.

운영하며 쌓은 것들

자동 업데이트는 양날의 검이다. Komodo는 새 이미지 감지 시 자동 재배포도 가능하지만, 모든 서비스에 켜두면 "어느 날 아침 문제가 생긴 서비스"가 생긴다. 필자의 운영 원칙: 핵심 서비스는 수동 승인, 잡것은 자동 — 업데이트 배지를 보고 판단해 배포 버튼을 누르는 방식이다. 자동화의 최대 강점은 버튼 누르는 시간이 아니라 "무엇이 밀려있는지"가 한눈에 보인다는 데 있다.

롤백도 배포다. 이미지 태그를 고정해 쓰면(:latest 대신 :1.42.0 같은 방식) 문제가 생겼을 때 git에서 태그를 되돌리고 push → Komodo에서 배포, 이것이 롤백이다. latest 태그만 쓰면 롤백이 어렵다는 말은 늘 그래왔고, Komodo 구조에서는 특히 그렇다.

업데이트 전 백업은 여전히 수동 습관. Komodo는 배포를 편하게 해줄 뿐, 데이터베이스 백업을 대신해주지 않는다. 중요 서비스(DB 붙은 것들)는 업데이트 전 백업이 원칙이다.

트러블슈팅 정리

자주 묻는 질문

Portainer(10화)와 함께 써도 되나?

이 서버가 그렇게 쓰고 있다. Portainer는 상태 확인·급한 조작의 콘솔, Komodo는 업데이트·배포의 시스템. 역할이 겹치는 부분이 있지만, "보는 것"과 "업데이트 절차"를 나누면 오히려 깔끔하다.

업데이트를 전부 자동으로 맡겨도 되나?

잡다한 유틸리티는 가능하다. DB가 붙은 핵심 서비스는 자동을 꺼두고 수동 승인으로 — 자동 배포로 생긴 문제는 원인 파악보다 "언제 바뀌었지?"부터 찾아야 하기 때문이다.

git을 안 쓰고도 되나?

된다. 다만 Komodo의 진가는 git 기반 sync에서 나온다. compose 파일의 변경 이력·롤백·협업이 전부 git의 기능이기 때문이다. 파일 몇 개만 올리면 되니 이 기회에 git을 시작할 이유가 된다.

서버 한 대로 충분하다 연재 목차 — 시리즈 소개 · 1화. Home Assistant · 2화. Frigate + go2rtc · 3화. Seafile 13 · 4화. Immich · 5화. Vaultwarden · 6화. Mailcow · 7화. MinIO · 8화. Umami · 9화. GitLab · 10화. Portainer

실제 운영 서버에서 Core·에이전트 구성으로 업데이트 운영 중입니다.