Portainer로 웹에서 컨테이너 관리하기 (setup token 오류 해결) — 홈랩 입문 5편

Portainer는 검은 터미널 대신 웹 화면에서 Docker 컨테이너를 관리하게 해주는 무료 관리 도구입니다. 이걸 설치하면 마우스 클릭만으로 앱을 올리고 내리고 상태를 확인할 수 있어, 홈랩의 진입장벽이 확 낮아지죠. 다만 최근 Portainer 버전은 보안 강화로 'setup token'을 요구하는데, 정보가 적어 여기서 막히는 분이 많습니다. 이 글에서는 설치부터 그 함정 해결까지 제가 직접 겪은 과정 그대로 정리했습니다.

이 글은 4편(Docker 설치 + SSH 원격 접속)에서 이어집니다. Docker가 아직 설치 전이라면 4편을 먼저 진행하세요.

Portainer 설치 — 명령어 두 줄이면 끝

Portainer 설치는 Docker 명령어 두 줄이면 완료됩니다. 먼저 데이터를 저장할 공간(볼륨)을 만들고, 그다음 Portainer 컨테이너를 실행하는 순서입니다. 원격 접속된 윈도우 PowerShell 창에서 아래를 입력하세요.

docker volume create portainer_data
docker run -d -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

두 번째 명령은 파이프 없이 옵션만 긴 한 줄이라 통째로 붙여넣으면 됩니다. --restart=always 옵션 덕분에 서버를 재부팅해도 Portainer가 자동으로 다시 켜집니다. 설치가 끝나면 윈도우 브라우저 주소창에 https://내서버IP:9443(예: https://172.30.1.51:9443)을 입력합니다. 이때 '주의 요함' 또는 '연결이 비공개가 아닙니다' 경고가 뜨는데, 이건 아직 SSL 인증서가 없어서 나는 정상적인 표시입니다. 내 서버라 안전하니 '고급 → 계속 진행'으로 넘어가면 됩니다. 이 빨간 경고를 초록 자물쇠로 바꾸는 방법은 이후 SSL 편에서 다룹니다.

setup token 오류 — 계정 생성 버튼이 안 켜질 때

Portainer 첫 화면에서 관리자 계정을 만드는데, 비밀번호를 12자 이상 정확히 입력했는데도 'Create user' 버튼이 회색으로 활성화되지 않는 경우가 있습니다. 저도 이 문제로 한참 막혔는데, 원인은 최신 Portainer 버전의 보안 정책이었습니다. 로그를 확인해보면 답이 나옵니다.

docker logs portainer --tail 20

여기서 admin initialization ... require this setup token ... Start with --no-setup-token to disable라는 메시지가 보인다면, 이 버전은 계정 생성 시 'setup token'을 반드시 입력하도록 요구하는 것입니다. 예전 설치 자료만 보고 따라 하면 이 항목이 없어서 다들 여기서 막히죠. 해결법은 두 가지인데, 실습 환경에서는 토큰 요구를 아예 끄는 쪽이 훨씬 깔끔합니다. 기존 컨테이너를 지우고, 맨 끝에 --no-setup-token 옵션을 붙여 다시 실행하면 됩니다.

docker stop portainer
docker rm portainer
docker run -d -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest --no-setup-token

앞의 실행 명령과 똑같고 끝에 --no-setup-token만 추가된 형태입니다. 이제 브라우저에서 Ctrl + Shift + R로 강력 새로고침(또는 시크릿 창으로 접속)한 뒤, 사용자명 admin과 12자 이상 비밀번호를 넣으면 'Create user' 버튼이 활성화됩니다. 이 비밀번호는 앞으로 컨테이너를 관리하는 관문이니 반드시 메모해두세요.

대시보드 진입, 그리고 다음 단계

계정을 만들면 'Get Started' 화면에서 로컬 환경을 선택해 대시보드로 들어갑니다. 여기서부터는 검은 명령어 없이도 컨테이너 목록, 실행 상태, 로그, 자원 사용량을 웹 화면에서 한눈에 볼 수 있습니다. 앞서 터미널에서 띄웠던 hello-world 컨테이너나 Portainer 자신이 목록에 보일 텐데, 이 화면이 바로 홈랩의 첫 '결과물'입니다.

여기까지 오느라 계정 문제, 네트워크 브리지, SSH, setup token까지 여러 관문을 넘으셨다면 축하드립니다. 이 삽질들이 사실 홈랩 입문의 통과의례이자, 나중에 같은 데서 막힌 사람에게 가장 큰 도움이 되는 실전 지식입니다. 이제 환경이 완성됐으니, 다음 편부터는 진짜 재미있는 실전 앱을 하나씩 올려봅니다. 첫 앱은 설치가 쉽고 체감 효과가 큰 '집 전체 광고 차단기'입니다. → 6편. 외부에서 내 서버 접속하기 — DDNS 설정 또는 앱 실전 편으로 바로 가기.