본문으로 건너뛰기

웹 UI 기반 컨테이너 관리 툴 Portainer 설치 및 설정

본 매뉴얼은 도커를 기반으로 한 환경에서 Portainer를 설정하는 방법을 안내합니다.

iwinv에서 도커가 포함된 운영체제를 설치해 이용 중인 사용자는 '3. Portainer 로그인' 부터 설정을 진행할 수 있습니다.

*Portainer는 데이터센터, 클라우드, 엣지 등 다양한 환경에서 쿠버네티스(Kubernetes), 도커(Docker), 스웜(Swarm), 노매드(Nomad)와 같이 쉽게 도커를 배포하고 구성할 때 사용하는 웹 UI 기반 관리 툴입니다.

가이드 안내​

가이드
  • iwinv 가상서버는 웹에서 콘솔 서비스를 제공하기 때문에 웹 계정을 도용당하게 될 경우 가상서버 보안에 취약할 수 있습니다.
  • GRUB Password를 설정하면 GRUB 진입 시 패스워드가 필요하기 때문에 가상서버 도용을 방지할 수 있습니다.
  • 해당 내용은 가상서버 뿐만 아니라 물리서버에서도 적용 가능한 방법입니다.

✅ 테스트 환경 : Ubuntu 24.04 LTS
✅ 난이도 : 초급

주의사항​

  • 리부팅 작업이 동반될 수 있으므로 서버가 정상적으로 올라오지 않는 경우가 발생할 수 있으니 유의해야 합니다.
  • 작업 전 가상서버 이미지 생성 백업을 권장드립니다.
  • 반드시 서버를 사용하지 않거나 접속자가 없는 시간을 선택해서 해당 작업을 진행합니다.
  • 리부팅 과정에서 서버가 정상적으로 부팅되지 않을수도 있습니다.

1. Docker 설치​

Portainer에 앞서 도커를 설치해야 합니다.

참고로 본 매뉴얼은 Ubuntu 24.04 LTS 버전을 기준으로 도커와 Portainer를 설치하는 과정을 설명합니다.
도커 설치를 위해 다음과 같이 공식 리포지토리에 등록해 최신버전의 Docker를 설치합니다.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

# To install the latest version, run:
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

도커를 시작하고 부팅 시 자동으로 구동되도록 설정합니다.

systemctl start docker
systemctl enable docker

설치가 잘 되었다면 아래 명령어로 확인해 줍니다.

systemctl status docker

우분투에서 도커 엔진 설치 참고 링크 : https://docs.docker.com/engine/install/ubuntu

2. Portainer 설치​

Portainer 설치에 앞서 사용할 볼륨을 생성합니다.

# 볼륨 디렉터리 생성
docker volume create portainer_data

Portainer는 컨테이너 이미지 형태로 제공됩니다. 도커 환경은 컨테이너 생성시 필요한 이미지가 없을 때 자동으로 다운로드를 합니다.
따라서 다음과 같은 명령을 실행하여 이미지 다운로드와 컨테이너를 동시에 실행할 수 있습니다.

# portainer 설치
docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

아래는 잘 실행된 모습입니다.

docker ps

CONTAINER ID   IMAGE                           COMMAND        CREATED          STATUS          PORTS                                                                                                NAMES
bc579c117546   portainer/portainer-ce:latest   "/portainer"   38 seconds ago   Up 34 seconds   0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp   portainer

3. Portainer 로그인​

이제 브라우저를 열어 https://[내 IP]:9443 으로 접속합니다.
초기 관리자 계정을 생성하고 패스워드를 설정합니다.

포테이너 첫 로그인 화면

아래는 처음으로 로그인 시 나오는 Home 화면이고 여기선 연결 된 도커 서버들을 관리하게 됩니다.

Home 메인 화면

현재는 local(내 PC) 만보이는데 눌러보면 컨테이너나 이미지 등을 관리하고 대시보드 화면이 나오게 됩니다.

local 대시보드 화면

그리고 컨테이너를 눌러보면 생성된 컨테이너들을 관리 할 수 있고 여기서 생성, 삭제 등을 GUI로 간단하게 작업 할 수 있습니다.

container 리스트 화면

4. 이미지 생성​

이미지를 다운로드 하여 서비스를 구동하는 방법을 알아보겠습니다.

대시보드 화면 좌측 메뉴에서 **[Image]**를 선택합니다.
Registry는 도커 허브로 그대로 두고 이미지에서 원하는 이미지를 검색합니다.
저희는 간단한 테스트를 하기 위해 이미지를 httpd로 진행하겠습니다.

이미지 생성 화면

**[Pull the image]**를 눌러 이미지를 불러와 줍니다. 그렇게 되면 아래처럼 이미지가 불러와 집니다.

이미지 생성 완료 화면

5. 볼륨 생성​

다음으로 httpd에서 사용할 볼륨을 생성할 차례입니다.
볼륨을 생성하면 컨테이너를 실수로 삭제하거나 장애로 유실해도 데이터를 보존할 수 있습니다.

추가 디스크 형태로 생성하므로 볼륨을 다른 컨테이너에 연결하는것도 가능하며 필요 시 여러 컨테이너가 특정 볼륨을 공유할 수도 있습니다.

좌측 [Volumes] 메뉴를 선택하면 다음과 같이 Portainer 설정 정보를 담고 있는 기본 Portainer_date 볼륨이 보입니다. 이 화면에서 [Add volumes] 버튼을 선택합니다.

볼륨 화면

아래 화면에서 이름 입력 상자에 볼륨 이름을 입력합니다.
httpd에서 사용할 것이므로 볼륨 구분을 위해 httpd_date로 이름을 붙입니다.

일반적인 볼륨 생성이므로 다른 설정을 하지 않고 [Create the Volume] 버튼을 누릅니다.

볼륨생성 화면

볼륨이 생성되면 다음과 같이 httpd_date라는 이름으로 만들어진 것을 확인할 수 있습니다.

볼륨생성 완료 화면

6. 컨테이너 생성​

다음으로 컨테이너 생성 과정을 알아보겠습니다. 대시보드의 좌측 메뉴에서 Containers를 선택합니다. Containers 페이지는 Portainer의 컨테이너를 생성, 삭제 하는 등 운영 관리할 수 있는 기능을 제공합니다.

container 리스트 화면

이제 httpd 컨테이너를 생성하기 위해 Add container 버튼을 누릅니다.

container 생성1 화면

container 생성2 화면

container 생성3 화면

컨테이너 생성을 위해 화면에서 [Add volumes] 버튼을 누릅니다. 컨테이너 생성을 위한 레이어 팝업창이 활성화되면 아래 해당하는 위치에 설정을 입력합니다.

이름(Name) : 컨테이너의 이름 입력

이미지(Image) : 컨테이너에 설치할 다운로드 받은 이미지 이름을 입력합니다. httpd를 입력하면 우측 Registry 풀다운 메뉴에서 선택 가능한 이미지가 검색됩니다.

포트 맵핑(Port mapping) : 컨테이너(container) 포트와 도커가 설치된 서버(Host)의 포트를 입력합니다. 두 포트가 맵핑되어야 외부 서비스가 가능합니다.

볼륨 맵핑(volume mapping) : 연결할 미리 생성한 볼륨을 지정합니다. 본 매뉴얼에서는 홈페이지 소스 기본 디렉토리(/usr/local/apache2/htdocs)로 연결을 설정하였습니다. 마운트할 디렉토리를 입력하고 생성한 볼륨을 선택합니다.

재시작 정책(Restart policy) : 컨테이너에 재시작 정책을 설정합니다. 본 매뉴얼에서는 Alwayes로 선택하였습니다.

  • Never : 종료 시 컨테이너를 자동으로 다시 시작하지 않음.
  • Always : 도커에서 서버가 구동될 때 컨테이너도 함께 시작.
  • On failure : 컨테이너가 0이 아닌 종료 상태로 종료되는 경우 다시 시작.
  • Unless stopped : 정상적인 컨테이너 중지를 제외하고 도커 실행 시 컨테이너 다시 시작.

참고로 예제에서 따로 설명하지 않지만 Runtime&Resource 탭에서 컨테이너에 할당할 메모리와 CPU 사양을 제한을 지정할 수 있습니다.
이외에도 User 메뉴를 통해 사용자와 그룹을 생성할 수 있고, 이 설정 화면에서 [Restricted] 버튼을 통해 사용자와 그룹의 접근 권한을 컨테이너 단위로 설정할 수도 있습니다.

모든 설정을 마쳤다면 [Deploy the container] 버튼을 눌러 컨테이너를 생성합니다.

container 생성 완료 화면

성공적으로 컨테이너가 생성되면 다음과 같이 구성 상태를 확인할 수 있습니다. Quick actions 부분에 표시된 아이콘의 의미는 다음과 같습니다.

  • 그래프 : 메모리, CPU, 네트워크 I/O지원 사용량을 뜻하며, 최소 5초 단위로 갱신됨
  • 문서 : 컨테이너 로그
  • 화살표/프롬프트 : 쉘 프롬프트 연결
  • 느낌표 : 컨테이너 상세 정보

container stat 화면

위 화면에서 그래프 모양의 아이콘을 클릭하면 컨테이너의 자원 사용량을 다음과 같이 대시보드 형태로 모니터링할 수 있습니다.
상태 정보는 최소 5초 단위로 갱신됩니다.

container logs 화면

문서 아이콘을 누르면 다음과 같이 컨테이 구동 로그를 확인할 수 있습니다.

container console 화면

7. 외부 접근 테스트​

생성한 httpd 컨테이너 서비스가 외부에서도 접속이 잘 되는지 확인하려면 [Connect] 버튼을 눌러 접속 테스트해 봅니다.

container console 접속 화면

접속 후 다음과 같은 명령으로 httpd의 기본 디렉토리인 /usr/local/apache2/htdocs에 test.html 파일이 생성되고, 다음과 같이 웹 브라우저를 통해 html 파일이 열리는 것을 확인할 수 있습니다.

http 접속 화면

작업 후 확인 사항​

확인사항
  • 로그인이 정상적으로 되는지 확인합니다.
  • 시스템 리부팅 후 서비스나 서버에 문제가 없는지 점검합니다.
노트
  • OS나 버전에 따라 명령어의 차이가 있을 수 있습니다.