Docker 관리 도구(Portainer) 도입 시 겪은 시행착오 정리

운영 중인 서버에서 Docker 기반 서비스가 늘어나면서 컨테이너 상태와 리소스를 직관적으로 확인할 수 있는 관리 도구의 필요성을 느끼게 되었다.
이에 Docker 관리 UI 도구인 Portainer 도입을 검토했고 그 과정에서 겪은 시행착오와 최종 판단을 정리해본다.

---

1 .기존 운영 환경

현재 서버는 다음과 같은 Docker 컨테이너가 운영 중인 상태였다.

• nginx: 외부 요청 및 SSL 처리
• Spring Boot 웹 서비스
• Redis
• Daily Scheduler

모든 서비스는 Docker Compose로 관리되고 있으며, 운영 서버 특성상 기존 서비스에 영향을 주지 않는 것이 최우선 원칙이었다.

---

2. Portainer 도입 목적

• 실행중인 컨테이너 상태 확인
• 리소스 사용량 모니터링
• 로그 확인 및 컨테이너 관리 편의성 향상

---

3. 초기 접근 - nginx 리버스 프록시 방식

초기에는 보안 관점에서 Portainer를 직접 노출하지 않고 nginx 리버스 프록시를 통해 아래와 같은 형식으로 접근하려 했다.

https://서버도메인/portainer

이를 위해 다음 구조로 구성했다.

• Portainer 컨테이너 별도 구성
• nginx ↔ portainer Docker 네트워크로 연결
• nginx에서 /portainer 경로를 프록시

---

4. 문제 발생

nginx 설정 반영 후 재기동 시 아래와 같은 오류가 반복적 발생

[host not found in upstream "portainer"]

이 오류로 인해 nginx 컨테이너가 기동되지 않았고, 운영 서버 전체 서비스에 영향을 줄 수 있는 상황이 되었음.

---

5. 원인 분석

1) nginx와 portainer가 서로 다른 Docker 네트워크에 존재

2) Docker DNS는 컨테이너가 RUNNING 상태가 된 이후에 등록

---

6. 검토한 대안

문제를 해결하기 위해서 Docker DNS resolver 명시, proxy_pass 변수 방식, timeout 대기 스크립트 추가와 같은 시도를 해보았지만 운영 서버에서 사용하기에는 구성 복잡도와 장애 리스크가 증가한다는 판단이 들어 포기하였다.

---

7. 최종 결정 - 리버스 프록시 방식 포기

결국 운영 안정성을 최우선으로 고려하여 nginx 리버스 프록시 방식은 사용하지 않기로 결정했다.
Portainer는 다음과 같이 가장 단순한 구조로 구성했다.

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    ports:
      - "포트:포트"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /경로/portainer/data:/data
      
      
// 접속 방식은 아래와 같음
https:// 서버IP:포트

---

8. 보안 추가 사항

운영 서버이기 때문에 다음 사항을 함께 추가했다.

• 방화벽을 통한 접근 IP 제한
• 관리자 계정 비밀번호 수준 강화
• 내부망 접근 전용 구성

---

9. 결과

• Portainer 정상 기동
• 컨테이너 상태, 로그, 리소스 확인 가능
• 운영 리스크 최소화

---

기술적으로 가능한 구조보단 장애 가능성이 가장 낮은 구조가 우선이다.