10화. Portainer — 도커를 터미널 없이 다루기 (웹 관리 콘솔)

도커를 쓰다 보면 "그 컨테이너 로그 좀 볼래" "재시작 좀 해줘" 같은 단순 명령을 위해 터미널을 열게 된다. 혼자면 그래도 되는데, 터미널을 못 다루는 동료에게 "컨테이너 재시작 좀 부탁해"라고 부탁하는 순간 문제가 된다. Portainer는 도커 전체를 브라우저로 관리하는 웹 콘솔이다. 상태 확인부터 로그, 콘솔 접속, 스택 배포까지 — CLI 없이도 도커를 다룰 수 있게 해준다.

이런 때 유용합니다

• 컨테이너가 몇 개나 돌고 있는지, 무엇이 죽었는지 한눈에 보고 싶을 때. 대시보드에 상태·재시작 횟수·리소스가 그려진다.
• 터미널을 못 쓰는 동료에게 서버 관리를 맡기고 싶을 때. 웹 화면에서 버튼으로 재시작·로그 확인이 가능하다.
• 급할 때 컨테이너 안으로 들어가야 할 때. 웹에서 바로 셸 콘솔이 열린다.
• docker compose 파일로 스택을 배포하고 싶을 때. 웹 에디터에 붙여넣어 배포하는 "스택" 기능이 있다.
• 실수로 docker rm을 눌러본 경험이 있을 때. 삭제 버튼에 확인 절차가 있다. (버튼이 늘 위험한 건 아니다만.)

필요한 것은 도커와 포트 하나뿐이다. 다만 한 가지 큰 전제가 있으니 설치 방법 다음에 다룬다.

Portainer는 어떤 프로그램인가

Portainer는 도커(및 쿠버네티스) 환경을 웹으로 관리하는 오픈소스 관리 콘솔이다. 도커 엔진의 모든 기능 — 컨테이너, 이미지, 볼륨, 네트워크, 스택 — 을 웹 UI로 노출한다.

에디션은 무료 CE(Community Edition)와 유료 BE가 있는데, 개인·소규모 서버라면 CE로 충분하다. 이 글도 CE 기준이다.

전체 구성

flowchart LR
    U1["관리자 - 전체 제어"] --> PT
    U2["팀원 - 조회·재시작"] --> PT
    subgraph SRV["Docker 서버"]
        PT["Portainer - 웹 관리 콘솔"]
        DK["Docker 엔진"]
        DK --> C1["컨테이너들"]
        DK --> C2["스택 · 볼륨 · 네트워크"]
    end
    PT -->|docker.sock| DK

Portainer는 도커의 제어 소켓(/var/run/docker.sock)을 연결받아 엔진을 조작한다. 이 소켓은 서버의 루트 권한과 같다 — 이 사실이 곧 설치 시의 최대 주의사항이다.

설치 방법

1단계 — 컨테이너

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /opt/docker/portainer/data:/data
    ports:
      - "9443:9443"   # 웹 UI (HTTPS)
      - "8000:8000"   # 에지 에이전트용 (필요 없으면 생략)

2단계 — 초기 관리자 계정, 여기서 실수 많다

https://서버IP:9443에 접속하면 관리자 계정 생성 화면이 나온다. 이 화면에는 보안 타이머가 있어서 몇 분 안에 생성하지 않으면 잠겨버린다. 잠기면 볼륨을 비우고 재설치해야 하니, 준비된 상태로 접속해 바로 만들자.

3단계 — 도메인 붙이기

9443 포트를 그대로 쓰면 자체 서명 인증서 경고가 뜬다. 리버스 프록시 뒤에 붙여 도메인+정상 인증서로 서비스하는 것이 편하다. 이때 접근 제한(사설망 허용, 접속 IP 제한 등)을 함께 거는 것을 강력히 권한다 — 다음 절의 이유 때문이다.

4단계 — 권한 정리

설정 → Users에서 계정을 나눈다. 관리자는 최소화하고, 팀원에게는 특정 환경의 읽기·재시작 권한만 주는 식으로 정리하면 실수로 전체 스택을 지우는 사고를 막을 수 있다.

docker.sock의 무게 — 알고 쓰자

Portainer를 도커 소켓에 연결하는 것은 그 웹 콘솔에 서버의 루트 권한을 준다는 뜻이다. 소켓에 접근할 수 있는 누구나 컨테이너를 띄워 호스트 파일시스템을 읽을 수 있기 때문이다. 그래서:

• 포트는 사설망에서만 열거나 프록시에서 접속 IP를 제한한다
• 관리자 계정은 강한 비밀번호+2FA(설정 지원)를 걸고, 공유하지 않는다
• 도메인 노출 시 검색엔진에 잡히지 않게 noindex 처리를 하고, 로그인 시도 로그를 가끔 본다

이 정도만 지키면 "터미널 없는 도커 관리"의 편의를 아주 안전하게 누릴 수 있다.

운영하며 쌓은 것들

웹 콘솔의 가치는 '급할 때'다. 평소엔 CLI로 충분하지만, 외출 중에 알림이 오고 폰으로 열어봤을 때 — 웹에서 재시작 버튼 하나로 해결되는 경험은 한 번 익숙해지면 못 돌아간다.

스택 기능은 compose 관리 화면이다. 웹 에디터에 compose 내용을 붙여 배포하면 이후 그 스택을 화면에서 관리할 수 있다. 다만 원본 compose 파일이 어디 있는지는 계속 CLI로 관리하는 것이 안전하다 — 웹에서 배포한 스택은 Portainer 데이터베이스에 정의가 남으므로, 파일 기반 운영과 섞이면 어느 쪽이 진짜인지 헷갈리기 시작한다. 필자는 "초기 배포만 웹, 이후 변경은 파일" 원칙으로 운영한다.

로그 검색이 생각보다 자주 쓰인다. 컨테이너 화면의 로그 뷰어는 검색·자동 새로고침을 지원한다. 문제 추적할 때 docker logs -f를 치는 것과 같은 일을 브라우저 탭에서 하게 된다.

트러블슈팅 정리

자주 묻는 질문

다음 화의 Komodo와 뭐가 다른가?

Portainer는 관리와 모니터링의 콘솔이고, Komodo는 여러 서버의 스택 업데이트를 일괄 오케스트레이션하는 도구에 가깝다. 이 서버에서는 "보는 것과 급한 조작은 Portainer, 정기 업데이트는 Komodo"로 역할을 나눈다. 다음 화에서 다룬다.

docker.sock을 여는 건 위험하지 않나?

맞다. 그래서 접근 제어(사설망·IP 제한, 강한 계정, 2FA)가 사실상 필수다. 그래도 불안하면 소켓 프록시 도구로 필요한 API만 노출하는 방법이 있다.

CLI를 이제 안 써도 되나?

반대다. Portainer는 CLI를 대체하지 않고 보조한다. compose 파일 기반의 근본 운영은 유지하되, 확인·급한 조작·위임을 웹으로 하는 구성이 가장 안정적이었다.

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

실제 운영 서버에서 관리 콘솔로 사용 중입니다.