Docker Compose로 Portainer 쉽게 설치하기: 컨테이너 관리가 이렇게 쉬울 줄이야! 🐳

안녕하세요, 여러분! 오늘은 Docker 컨테이너를 시각적으로, 그리고 아주 쉽게 관리할 수 있게 해주는 강력한 도구인 Portainer를 Docker Compose를 활용하여 설치하고 사용하는 방법에 대해 상세하게 알아보겠습니다. 복잡한 CLI 명령어를 외우거나 매번 입력하는 것에 지치셨다면, 이 글이 여러분의 컨테이너 관리 라이프를 한 단계 업그레이드해 줄 것입니다! ✨

🚀 1. Portainer란 무엇인가요?

Portainer는 Docker, Docker Swarm, Kubernetes와 같은 컨테이너 오케스트레이션 플랫폼을 위한 오픈 소스 시각화 관리 도구입니다. 간단히 말해, 컨테이너를 명령어가 아닌 웹 기반의 깔끔한 대시보드를 통해 생성, 배포, 관리, 모니터링할 수 있게 해주는 UI(사용자 인터페이스) 도구라고 생각하시면 됩니다.

Portainer의 주요 특징:

• 직관적인 대시보드: 현재 실행 중인 컨테이너, 이미지, 볼륨, 네트워크 등의 상태를 한눈에 파악할 수 있습니다.
• 쉬운 컨테이너 관리: 몇 번의 클릭만으로 컨테이너를 시작, 중지, 재시작, 삭제할 수 있으며, 로그 확인, 셸 접속 등도 가능합니다.
• 애플리케이션 템플릿: 미리 정의된 템플릿을 사용하여 WordPress, Nginx 등 인기 있는 애플리케이션을 쉽게 배포할 수 있습니다.
• 볼륨 및 네트워크 관리: Docker 볼륨과 네트워크를 시각적으로 생성하고 관리할 수 있습니다.
• 사용자 및 접근 제어: 여러 사용자를 생성하고 각 사용자에게 특정 리소스에 대한 접근 권한을 부여하여 팀 단위 관리에 용이합니다.
• 멀티 환경 관리: 여러 Docker 호스트 또는 Swarm 클러스터를 Portainer 하나로 통합 관리할 수 있습니다.

📝 2. 왜 Docker Compose를 사용해야 할까요?

Portainer를 설치하는 방법은 다양하지만, 그중에서도 Docker Compose를 사용하는 것이 가장 간편하고 재현성이 높으며 관리하기 용이합니다.

Docker Compose란?

Docker Compose는 여러 개의 Docker 컨테이너를 함께 정의하고 실행하기 위한 도구입니다. docker-compose.yml이라는 YAML 파일을 사용하여 애플리케이션의 서비스, 네트워크, 볼륨 등을 한 번에 정의하고, 단일 명령어로 전체 애플리케이션 스택을 빌드하고 실행할 수 있습니다.

Portainer 설치에 Docker Compose를 활용하는 이점:

• 간결성: 복잡한 docker run 명령어를 여러 개 입력할 필요 없이, 단 하나의 docker-compose.yml 파일로 모든 설정을 정의할 수 있습니다.
• 재현성: YAML 파일만 있다면 어떤 환경에서든 동일한 설정으로 Portainer를 빠르게 배포할 수 있습니다. 백업 및 복원에도 유리합니다.
• 쉬운 관리: Portainer 서비스 시작, 중지, 업데이트 등을 docker-compose 명령어로 손쉽게 제어할 수 있습니다.
• 버전 관리: docker-compose.yml 파일을 Git과 같은 버전 관리 시스템에 저장하여 변경 이력을 관리할 수 있습니다.

🛠️ 3. Portainer 설치를 위한 Docker Compose 파일 작성하기

이제 Docker Compose를 사용하여 Portainer를 설치해 봅시다. 시작하기 전에, 여러분의 시스템에 Docker와 Docker Compose가 설치되어 있어야 합니다.

사전 준비:

1. Docker 설치 확인: 터미널에서 docker --version 명령어를 실행하여 Docker가 설치되어 있는지 확인합니다.
2. Docker Compose 설치 확인: docker compose version 또는 docker-compose --version 명령어를 실행하여 Docker Compose가 설치되어 있는지 확인합니다. (최신 Docker 버전에는 docker compose 명령어가 내장되어 있습니다.)

단계별 설치:

1. Portainer 설치를 위한 디렉토리 생성 먼저, Portainer 관련 파일을 저장할 디렉토리를 생성하고 해당 디렉토리로 이동합니다.

mkdir portainer
cd portainer

2. docker-compose.yml 파일 생성 portainer 디렉토리 안에 docker-compose.yml이라는 이름으로 파일을 생성하고 다음 내용을 붙여넣습니다.

touch docker-compose.yml

3. docker-compose.yml 파일 내용 작성 이제 docker-compose.yml 파일을 텍스트 편집기(vi, nano, VS Code 등)로 열어 다음 내용을 작성합니다.

version: '3.8' # Docker Compose 파일 버전 (최신 권장)

services:
  portainer:
    image: portainer/portainer-ce:latest # Portainer CE(Community Edition) 이미지 사용
    container_name: portainer # 컨테이너 이름 지정 (선택 사항)
    restart: always # 컨테이너 종료 시 항상 재시작 (예: 서버 재부팅 시 자동 시작)
    ports:
      - "9000:9000" # Portainer 웹 UI 접속 포트 (호스트:컨테이너)
      - "8000:8000" # Portainer Edge Agent 통신용 포트 (필요한 경우 활성화)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Docker 데몬 소켓 마운트 (필수)
      - portainer_data:/data # Portainer 데이터 영속성 유지를 위한 볼륨 마운트

volumes:
  portainer_data: # Portainer 데이터를 저장할 명명된 볼륨 정의

각 설정 항목 설명:

• version: '3.8' : Docker Compose 파일의 버전을 명시합니다. 최신 기능을 활용하기 위해 3.x 버전을 사용하는 것이 좋습니다.
• services: : 이 섹션 아래에 실행할 서비스(컨테이너)들을 정의합니다.
• portainer: : portainer라는 이름의 서비스를 정의합니다. 이는 여러분이 원하는 어떤 이름으로든 변경할 수 있습니다.
• image: portainer/portainer-ce:latest : Portainer Community Edition의 최신 이미지를 사용하겠다는 의미입니다. :latest 태그는 항상 최신 버전을 가져오게 합니다. 특정 버전을 사용하려면 portainer/portainer-ce:2.19.4와 같이 명시할 수 있습니다.
• container_name: portainer : 생성될 컨테이너의 이름을 portainer로 지정합니다. 이 이름을 통해 docker stop portainer와 같이 쉽게 제어할 수 있습니다.
• restart: always : 컨테이너가 어떤 이유로든 종료되거나 Docker 데몬이 재시작될 때 항상 이 컨테이너를 다시 시작하도록 설정합니다.
• ports: : 호스트와 컨테이너 간의 포트 매핑을 정의합니다.
  • - "9000:9000" : 호스트의 9000번 포트로 들어오는 요청을 컨테이너의 9000번 포트로 전달합니다. Portainer 웹 UI에 접속하는 데 사용됩니다.
  • - "8000:8000" : Portainer Edge Agent를 사용하여 원격 환경을 관리할 때 필요한 포트입니다. 현재는 필요 없더라도 미래를 위해 열어두는 것을 권장합니다.
• volumes: : 컨테이너와 호스트 간의 볼륨 매핑을 정의합니다. 데이터 영속성을 위해 매우 중요합니다.
  • - /var/run/docker.sock:/var/run/docker.sock : 가장 중요한 부분 중 하나입니다. 호스트의 Docker 데몬 소켓을 Portainer 컨테이너 내부에 마운트하여 Portainer가 호스트의 Docker 환경을 제어할 수 있도록 합니다. 이 볼륨이 없으면 Portainer는 아무 컨테이너도 관리할 수 없습니다.
  • - portainer_data:/data : portainer_data라는 이름의 명명된 볼륨(named volume)을 컨테이너 내부의 /data 디렉토리에 마운트합니다. Portainer의 설정, 사용자 정보, 애플리케이션 데이터 등이 이 볼륨에 저장되어 컨테이너가 삭제되어도 데이터가 보존됩니다.
• volumes: (최상위 레벨) : portainer_data와 같이 사용할 명명된 볼륨을 정의합니다. Docker가 이 볼륨을 자동으로 생성하고 관리합니다.

▶️ 4. Docker Compose로 Portainer 실행 및 접근하기

docker-compose.yml 파일 작성이 완료되었다면, 이제 Portainer를 실행하고 웹 UI에 접속할 차례입니다.

1. Portainer 실행 docker-compose.yml 파일이 있는 디렉토리(portainer 디렉토리)에서 다음 명령어를 실행합니다.

docker compose up -d

• up: docker-compose.yml 파일에 정의된 서비스를 시작합니다.
• -d: (detached mode) 백그라운드에서 컨테이너를 실행하여 터미널을 다시 사용할 수 있게 합니다.

명령어를 실행하면 Docker 이미지를 다운로드하고 Portainer 컨테이너를 생성하여 실행하는 과정이 표시됩니다.

2. 실행 확인 Portainer 컨테이너가 정상적으로 실행 중인지 확인합니다.

docker ps

출력 결과에 portainer/portainer-ce 이미지를 사용하는 portainer 컨테이너가 Up 상태로 표시되어야 합니다.

CONTAINER ID   IMAGE                          COMMAND        CREATED         STATUS         PORTS                                                    NAMES
xxxxxxxxxxxx   portainer/portainer-ce:latest  "/portainer"   5 seconds ago   Up 4 seconds   0.0.0.0:8000->8000/tcp, 0.0.0.0:9000->9000/tcp   portainer

3. Portainer 웹 UI 접속 웹 브라우저를 열고 다음 주소로 접속합니다.

http://localhost:9000

만약 Docker를 원격 서버에 설치했다면, localhost 대신 서버의 IP 주소를 입력하세요. (예: http://192.168.1.100:9000)

4. Portainer 초기 설정

• 관리자 계정 생성: 처음 접속하면 관리자 계정(Admin user)을 생성하라는 화면이 나타납니다. 강력한 비밀번호를 설정하고 “Create user” 버튼을 클릭합니다. 🔑
• 환경 선택: 다음 화면에서 Portainer가 관리할 Docker 환경을 선택해야 합니다. 일반적으로 단일 서버에 설치했다면 “Local” 환경을 선택합니다.
  • Local: Portainer가 설치된 현재 서버의 Docker 환경을 관리합니다.
  • Agent: 다른 원격 Docker 환경에 설치된 Portainer Agent와 연결하여 관리합니다.
  • Kubernetes: Kubernetes 클러스터를 관리합니다.
  • Azure ACI: Azure Container Instances를 관리합니다. “Local”을 선택한 후 “Connect” 버튼을 클릭합니다.

이제 Portainer 대시보드에 접속되어 여러분의 Docker 환경을 시각적으로 관리할 준비가 완료되었습니다! 🎉

✨ 5. Portainer 사용 팁 및 주요 기능 둘러보기

Portainer 대시보드에 접속하면 여러 메뉴를 통해 Docker 환경을 편리하게 관리할 수 있습니다.

• Dashboard (대시보드): 현재 환경의 컨테이너, 이미지, 볼륨 등 전체적인 현황을 요약해서 보여줍니다.
• Containers (컨테이너): 실행 중이거나 중지된 모든 컨테이너 목록을 볼 수 있습니다. 컨테이너를 클릭하여 로그 확인, 상태 변경(시작/중지/재시작), 환경 변수 변경, 셸 접속 등 상세 작업을 할 수 있습니다. 📦
• Images (이미지): 다운로드된 Docker 이미지 목록을 확인하고, 이미지 빌드나 삭제를 할 수 있습니다.
• Volumes (볼륨): 생성된 Docker 볼륨을 관리합니다. 컨테이너 데이터의 영속성을 유지하는 데 필수적입니다. 💾
• Networks (네트워크): Docker 네트워크를 생성하고 관리합니다. 컨테이너 간 통신 및 외부 접속 설정을 제어합니다. 🌐
• Stacks (스택): Docker Compose 파일(stack)을 사용하여 배포된 애플리케이션들을 관리합니다. YAML 파일을 업로드하거나 웹 에디터로 직접 작성하여 스택을 배포할 수 있습니다. 📝
• App Templates (애플리케이션 템플릿): 미리 정의된 템플릿을 사용하여 WordPress, Redis 등 인기 있는 애플리케이션을 클릭 몇 번으로 쉽게 배포할 수 있습니다. 🚀
• Users (사용자): 여러 사용자를 추가하고 권한을 관리하여 팀 프로젝트에 활용할 수 있습니다. 👥

🤔 6. 문제 해결 및 추가 고려사항

자주 발생하는 문제:

• 포트 충돌 (Address already in use): docker-compose.yml 파일에 설정된 9000번 또는 8000번 포트가 이미 다른 애플리케이션에 의해 사용 중인 경우 발생합니다. ports 섹션에서 9000:9000 대신 9001:9000과 같이 호스트 포트를 변경해 주세요. (예: - "9001:9000")
• /var/run/docker.sock 권한 문제: Portainer 컨테이너가 Docker 소켓에 접근할 수 없는 경우 발생합니다. 일반적으로 root 사용자나 docker 그룹에 속한 사용자 계정으로 실행하면 문제가 없습니다. 만약 권한 문제가 계속 발생한다면, docker.sock의 소유자 또는 그룹 권한을 확인해 보세요.
• Portainer 접속 불가: 방화벽(Firewall)에서 9000번 포트가 차단되어 있을 수 있습니다. 서버의 방화벽 설정을 확인하고 9000번 포트를 허용해야 합니다.

추가 고려사항:

• 보안:
  • Portainer는 강력한 관리 도구이므로, 웹 UI의 기본 9000번 포트를 외부에 직접 노출하는 것은 권장하지 않습니다. Nginx 또는 Caddy와 같은 리버스 프록시를 사용하여 HTTPS를 설정하고, 특정 IP에서만 접근을 허용하도록 방화벽을 구성하는 것이 좋습니다.
  • 관리자 비밀번호를 강력하게 설정하고 주기적으로 변경하세요.
• 업데이트: Portainer를 최신 버전으로 업데이트하려면, docker-compose.yml 파일이 있는 디렉토리에서 다음 명령어를 실행합니다.

  docker compose pull portainer # 최신 Portainer 이미지 다운로드
  docker compose up -d --force-recreate # 기존 컨테이너를 삭제하고 새 이미지로 다시 생성

• 데이터 백업: portainer_data 볼륨에는 Portainer의 모든 설정 및 데이터가 저장됩니다. 주기적으로 이 볼륨을 백업하여 혹시 모를 상황에 대비하는 것이 좋습니다. docker volume inspect portainer_data 명령어로 실제 저장 경로를 확인할 수 있습니다.

맺음말

이 글을 통해 Docker Compose를 활용하여 Portainer를 쉽고 안정적으로 설치하는 방법을 알아보았습니다. Portainer는 Docker 컨테이너 관리에 익숙하지 않은 사용자뿐만 아니라, 효율적인 관리를 원하는 숙련된 사용자에게도 매우 유용한 도구입니다.

이제 여러분도 Portainer의 직관적인 웹 UI를 통해 복잡한 CLI 명령 없이도 컨테이너를 자유자재로 다룰 수 있을 것입니다. 여러분의 컨테이너 관리 여정이 더욱 즐거워지기를 바랍니다! 🚀 궁금한 점이 있다면 언제든지 댓글로 질문해주세요.