본문으로 건너뛰기

설치와 기동

MAC이 대시보드를 띄우기도 전에 마주치는 문제들입니다.

dpkg -i 후에도 mac 명령을 찾을 수 없음​

Debian 패키지는 설치되었지만 셸이 아직 새 바이너리를 인식하지 못한 상태입니다.

  • 새 셸을 열거나, 현재 셸에서 hash -r을 실행하세요.
  • 설치 확인: dpkg -L mango-ai-center | grep /usr/bin/mac.

mac start가 /var/run/docker.sock에서 "permission denied"로 실패​

사용자가 docker 그룹에 들어 있지 않아 도커 데몬을 다룰 수 없는 경우입니다.

~$ sudo usermod -aG docker $USER
~$ newgrp docker     # 또는 로그아웃 후 다시 로그인
~$ mac start all

root로 실행해야 한다면 sudo를 붙여도 되지만, mac은 non-root 사용자로 동작하도록 설계되어 있습니다.

MAC_REGISTRY가 설정되지 않아 mac pull 실패​

MAC에는 기본 컨테이너 레지스트리가 없습니다. MAC_REGISTRY를 설정하지 않으면 mac pull이 이미지 이름을 해석할 수 없습니다.

~$ mac env set MAC_REGISTRY=<MangoBoost 안내 값 또는 프라이빗 미러>
~$ mac pull all

이미지 pull이 unauthorized / denied로 실패​

자격 증명이 필요한 레지스트리에서 받고 있거나, MAC_REGISTRY 경로가 잘못된 경우입니다.

  • MAC_REGISTRY 확인: mac env | grep MAC_REGISTRY
  • 공개 저장소를 사용한다면 파트너 게스트 계정으로 재인증하세요. docker login repo.mangoboost.io. 자격 증명은 contact@mangoboost.io에서 발급합니다.
  • 프라이빗 미러를 쓰는 경우 docker login <registry-host>을 한 번 수행한 뒤 mac pull 합니다.
  • 프라이빗 미러를 쓴다면 다음 이미지가 모두 존재하는지 확인합니다. mac/api-server, mac/web-ui, mac/metrics-bridge, mac/dcgm-exporter, mac/rocm-exporter, mac/nic-exporter, mac/sw-exporter, mac/sys-exporter, 그리고 SDK_AGENT_IMAGE가 가리키는 mango-sdk-agent.

일부 컨테이너가 restarting 상태에서 빠져나오지 못함​

~$ mac status
NAMES             STATUS        PORTS
mac-api-server    Restarting

컨테이너 로그를 확인합니다.

~$ docker logs mac-api-server

가장 흔한 원인은 다음과 같습니다.

  • 에이전트에서 마스터로 접근 불가 — 에이전트의 MASTER_IP가 잘못 설정되었거나, 마스터가 다운된 상태.
  • 포트 충돌 — 다른 서비스가 23000, 28080, 29090 중 하나를 점유한 경우. sudo ss -tlnp | grep :29090으로 충돌을 찾아 해당 프로세스를 중지하거나, mac env의 MAC_*_PORT 오버라이드로 MAC 포트를 옮기세요.
  • 디스크 부족 — Prometheus와 Loki는 데이터 볼륨이 가득 차면 기동을 거부합니다. df -h /var/lib/docker로 확인하세요.