왜 Portainer인가

Filebrowser, Immich, Vaultwarden, Prometheus, Grafana… 서비스가 하나씩 늘어나다 보니 컨테이너가 어느새 8개가 넘었다. 매번 SSH 접속해서 docker ps, docker logs, docker compose restart 치는 게 점점 번거로워졌다.

Portainer CE는 Docker를 웹 UI로 관리할 수 있는 오픈소스 도구다. 컨테이너 시작/중지/재시작, 실시간 로그 확인, 볼륨/네트워크 관리까지 브라우저에서 다 된다. CE(Community Edition)는 무료다.

설치

1. 디렉토리 생성

mkdir -p ~/portainer && cd ~/portainer

2. docker-compose.yml 작성

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: always
    ports:
      - "19000:9000"
      - "18000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

핵심은 /var/run/docker.sock을 마운트하는 것이다. 이를 통해 Portainer가 호스트의 Docker 데몬에 직접 접근할 수 있다.

포트는 기존 서비스들과 충돌하지 않도록 10000번대로 설정했다.

포트 용도
19000 Portainer 웹 UI
18000 Edge Agent 터널 (원격 환경 연결용)

3. 실행

docker compose up -d

4. 초기 설정

브라우저에서 http://100.109.108.36:19000 접속 후 admin 계정을 생성한다.

⚠️ 컨테이너 실행 후 5분 이내에 초기 계정을 만들어야 한다. 시간이 지나면 보안상 접근이 차단되므로 docker compose restart portainer로 재시작해야 한다.

결과

Portainer 대시보드 - 컨테이너 목록

설치 후 현재 홈서버에서 실행 중인 모든 컨테이너를 한눈에 볼 수 있다.

컨테이너 상태
filebrowser healthy ✅
grafana running ✅
immich_machine_learning healthy ✅
immich_postgres healthy ✅
immich_redis healthy ✅
immich_server healthy ✅
portainer running ✅
prometheus running ✅

컨테이너별로 로그 확인, 시작/중지, 환경변수, 마운트 볼륨 정보까지 GUI에서 바로 볼 수 있다.

접근 방식

Portainer는 Docker 소켓에 직접 접근하는 민감한 도구라 외부에 열지 않고 Tailscale VPN 안에서만 접근한다.

Portainer UI → http://100.109.108.36:19000 (Tailscale VPN으로만 접근)

Nginx 리버스 프록시로 외부에 노출하지 않는다. 누군가 Portainer에 접근하면 서버의 모든 컨테이너를 제어할 수 있기 때문이다.

정리

  • Docker Compose 파일 하나로 설치가 끝난다
  • /var/run/docker.sock 마운트가 핵심
  • 컨테이너 실행 후 5분 안에 초기 계정 생성할 것
  • 보안상 VPN 안에서만 접근하고 외부에는 절대 열지 말 것

다음 편에서는 Prometheus + Grafana + Node Exporter로 홈서버와 OCI 서버를 동시에 모니터링하는 환경을 구성한다.