Docker 초보자 필수! Portainer 설치 및 활용 가이드

복잡한 건 딱 질색인데 Docker는 써보고 싶다?
그럴 때 쓰라고 있는 게 Portainer입니다.

먼저, 홈서버 네트워크 기초부터 잡고 싶다면 아래 글을 먼저 보고 오셔도 좋습니다.

👉 시놀로지 NAS + 미니PC VLAN 기반 NFS 완벽 설정 가이드 (Ubuntu 24 + Synology DS923+)

이제 본론으로 들어가겠습니다.

1. Portainer, 왜 써야 하나요? (3가지 이유만 보겠습니다)

Portainer를 한 줄로 정의하면 이겁니다.

“검은 화면(CLI) 공포증을 없애주는 Docker GUI 대시보드”

조금만 디테일을 추가해 보면:

시각화
- docker ps, docker logs 대신
  컨테이너 상태, 리소스 사용량, 로그를 한 화면에서 그래프로 확인할 수 있습니다.
편의성
- 컨테이너 재시작, 중지, 삭제, 로그 확인을 마우스 클릭 몇 번으로 해결.
- 볼륨, 네트워크, 이미지 관리까지 대부분의 작업을 웹 UI에서 처리할 수 있습니다.
Stacks 기능 (핵심)
- 원래라면 docker-compose up -d 같은 명령어로 돌려야 하는 구성을
  웹 화면에서 YAML만 붙여넣고 “Deploy the stack” 버튼 한 번으로 배포할 수 있습니다.
- Nextcloud, Nginx Proxy Manager, Jellyfin, qBittorrent… 이런 것들을 모두 Portainer Stacks에서 관리하게 됩니다.

결론만 말하면,

미니PC 홈서버를 시작할 거라면, 첫 번째로 올려야 할 컨테이너가 바로 Portainer입니다.

2. 30초 컷! Portainer 설치 (SSH에서 명령어 2줄이면 끝)

전제 조건:

Docker / Docker Compose는 이미 설치되어 있다고 가정합니다.
Linux (Ubuntu 등) 서버에서 실행합니다.

SSH로 서버에 접속한 뒤, 아래 두 줄만 입력하면 됩니다.

2-1. Portainer 데이터용 볼륨 생성

docker volume create portainer_data

2-2. Portainer 컨테이너 실행

docker run -d \
  -p 8000:8000 -p 9000:9000 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

옵션 간단 설명

-d : 백그라운드(detached) 모드로 실행
-p 8000:8000 : 에이전트용 포트 (기본값, 크게 신경 안 써도 됩니다)
-p 9000:9000 : Portainer 웹 UI 접속 포트
--restart=always : 서버가 재부팅돼도 Portainer가 자동으로 다시 올라오도록 설정
-v /var/run/docker.sock:/var/run/docker.sock
→ 가장 중요
→ 호스트의 Docker 엔진에 Portainer가 직접 접근할 수 있도록 소켓을 연결
-v portainer_data:/data : 아까 만든 portainer_data 볼륨에 Portainer 설정/데이터 저장

여기까지 입력하면 이미 Portainer는 떠 있습니다.

3. 웹 브라우저에서 접속 & 초기 설정

같은 네트워크에 있는 PC의 브라우저에서 아래 주소 입력 http://서버IP:9000http://서버IP:9000 예: http://192.168.10.50:9000
처음 접속하면 관리자 계정 생성 화면이 뜹니다.
- 사용자명: admin (권장, 아니어도 상관 없음)
- 비밀번호: 충분히 강한 패스워드로 설정
“Create user” → “Get Started” 버튼을 누르면
Docker 대시보드 화면이 나타납니다.

여기까지가 Portainer 설치 끝입니다.
실제로 걸리는 시간은 30초~1분 사이일 겁니다.

4. 핵심 기능: Stacks가 뭔가요?

컨테이너 하나 둘 정도는 docker run으로 띄워도 크게 어렵지 않습니다.
문제는 아래처럼 서비스가 많아지기 시작할 때입니다.

Nginx Proxy Manager
Nextcloud
OnlyOffice
qBittorrent/Transmission
Jellyfin / Plex
Redis, MariaDB, Postgres …

이걸 전부 터미널에서 docker-compose로 관리하기 시작하면:

YAML 파일이 여기저기 흩어지고
어떤 서비스가 어디에 설치되어 있는지 헷갈리며
서버를 갈아탈 때마다 파일을 찾느라 고생을 하게 됩니다.

그래서 Portainer Stacks를 사용합니다.

4-1. Stacks 진입

Portainer 왼쪽 메뉴에서 “Stacks” 클릭
상단의 “Add stack” 버튼 클릭

4-2. docker-compose YAML 붙여넣기

예를 들어, Nginx Proxy Manager를 올린다고 하면:

Stack name에 nginx-proxy-manager 입력
“Web editor” 영역에 docker-compose.yml 내용을 그대로 붙여넣기
하단의 “Deploy the stack” 버튼 클릭

이걸로 끝입니다.

이제부터는:

시작/중지/재시작 → Stacks → 해당 스택 클릭 → 상단 버튼 클릭

로그 확인 → 컨테이너 클릭 → “Logs” 탭

환경 변수 수정, 볼륨 연결 변경 → 컨테이너 → “Duplicate/Edit”

실질적으로 “홈서버용 앱 스토어” 같은 느낌으로 쓰게 됩니다.

5. 마무리 – 홈서버의 출발점은 Portainer

복습 겸 정리해 보겠습니다.

Portainer는 뭐 하는 물건인가?
- Docker를 눈으로 보면서 클릭으로 제어하게 해주는 웹 대시보드
- 특히 Stacks 기능 덕분에 “YAML 붙여넣고 배포”만으로 여러 컨테이너를 한 번에 관리 가능
설치는 진짜 간단한가?
- 아래 명령머 복붙이면 끝입니다.

docker volume create portainer_data

docker run -d \
  -p 8000:8000 -p 9000:9000 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

그 다음 단계는?
- Nginx Proxy Manager, Nextcloud, Jellyfin, qBittorrent 같은 것들을
  모두 Portainer의 Stacks 메뉴에서 관리하게 되면,
- 터미널은 가끔 로그 확인할 때만 열어도 되는 수준이 됩니다.

마지막으로, Portainer 프로젝트가 어떻게 돌아가는지 궁금하다면 원본 저장소도 한 번씩 구경해 보세요.

👉 소스코드 및 공식 문서:
Portainer GitHub Repository

이제 docker ps 대신 브라우저 북마크에 http://서버IP:9000을 추가해 두시면 됩니다.
미니PC 홈서버의 첫 화면은 앞으로 Portainer가 될 거예요.