B_미디어자료정리 — 02. PhotoView 설치 메뉴얼

02. PhotoView 설치 메뉴얼

대상 기기: 맥미니 (루키) 사전 요구사항: macOS, Docker Desktop 또는 OrbStack, Tailscale 사진 소스: NAS (SMB 마운트) 접속 방법: Tailscale MagicDNS

---

📋 사전 준비물

항목	상태	확인 명령
macOS	필수	sw_vers
Docker Desktop	또는 OrbStack	docker --version
Tailscale	연결 상태 확인	tailscale status
NAS SMB 마운트	사진 폴더 접근 가능	ls /Volumes/...

---

🔧 1단계: Docker 설치 (없는 경우)

방법 A: Docker Desktop (공식, 무거움)

# https://www.docker.com/products/docker-desktop/ 에서 다운로드
# 또는 Homebrew
brew install --cask docker

방법 B: OrbStack (권장, 가벼움)

# https://orbstack.dev/ 에서 다운로드
# 또는 Homebrew
brew install --cask orbstack

💡 OrbStack 추천 이유: Docker Desktop보다 가볍고 빠름. 맥미니 리소스 절약.

---

🔧 2단계: NAS SMB 마운트 (맥미니에서)

Finder 방식 (GUI)

1. Finder → 이동 → 서버에 연결 (Cmd+K)
2. 주소 입력: smb://아이피또는호스트/공유이름
3. 사용자명/비밀번호 입력 후 연결

자동 마운트 (권장 — 재부팅 후 유지)

# /etc/auto_smb 파일 생성
sudo tee /etc/auto_smb << 'EOF'
# NAS 사진 폴더
photos    -fstype=smbfs,soft    ://psbot:@@Mini3388@mh-nas.local/backup/pinksky/개인관련/Media/라이트룸사진
EOF

# /etc/auto_master에 추가
echo "/-    auto_smb    -nosuid,noowners" | sudo tee -a /etc/auto_master

# automount 재시작
sudo automount -vc

마운트 확인

ls /Volumes/photos/        # 사진 파일 보이는지 확인
df -h | grep smb           # SMB 마운트 상태 확인

---

🔧 3단계: PhotoView docker-compose.yml 작성

📁 작업 폴더 생성

mkdir -p ~/photoview
cd ~/photoview

📝 docker-compose.yml

services:
  photoview:
    image: photoview/photoview:2
    container_name: photoview
    restart: unless-stopped
    ports:
      - "8000:80"
    environment:
      # SQLite 사용 (MariaDB 없이 단순화)
      PHOTOVIEW_DATABASE_DRIVER: sqlite
      PHOTOVIEW_SQLITE_PATH: /home/photoview/database/photoview.db
      PHOTOVIEW_LISTEN_IP: "0.0.0.0"
      # 지도 기능 (선택 — Mapbox 토큰 필요)
      # MAPBOX_TOKEN: "YOUR_MAPBOX_TOKEN"
    volumes:
      # 로컬 시간대
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/timezone:/etc/timezone:ro"
      # PhotoView DB 저장
      - "./database:/home/photoview/database"
      # 캐시/썸네일 저장
      - "./cache:/home/photoview/media-cache"
      # ⭐ NAS 사진 폴더 마운트 (읽기전용)
      - "/Volumes/photos:/photos:ro"
      # 추가 폴더가 있으면 여기에 더 마운트
      # - "/Volumes/photos2:/photos2:ro"
    # 맥에서는 보안 옵션 필요 없음 (Linux만 해당)
    # security_opt 제거

📝 .env (환경변수 파일)

# .env 파일은 docker-compose.yml에서 ${VAR} 문법으로 참조
# 이 minimal 설정에서는 거의 사용 안 함
# 필요하면 아빠가 Mapbox 토큰 같은 것만 추가

---

🔧 4단계: PhotoView 기동

cd ~/photoview

# 컨테이너 빌드 및 기동
docker compose up -d

# 로그 확인 (초기 설정 페이지 뜨는지)
docker compose logs -f photoview

접속 주소

환경	URL
맥미니 로컬	http://localhost:8000
Tailscale (같은 tailnet)	http://맥미니-tailscale-호스트.tail437af5.ts.net:8000
외부 (포트포워딩 시)	http://공인IP:8000 (비권장)

---

🔧 5단계: 초기 설정 (웹 UI)

첫 실행 시 나타나는 페이지

1. 관리자 계정 생성

   • Username: 아빠가 원하는 ID
   • Password: 안전한 비밀번호
   • Confirm Password: 재입력

2. 사진 라이브러리 경로 설정

   • ”+ Add new library” 클릭
   • Container path 입력: /photos
   • (이건 docker-compose에서 마운트한 경로)
   • Title: “NAS 사진” (아무 이름)

3. 첫 인덱싱 시작

   • PhotoView가 자동으로 90,577장 스캔 시작
   • 썸네일 생성 진행 → 시간 소요

---

🔧 6단계: 인덱싱 진행 모니터링

PhotoView UI에서 확인

• 왼쪽 사이드바 → “Dashboard” 또는 “Settings”
• 진행률/스캔된 사진 수 확인

맥미니 터미널에서 확인

# Docker 로그 실시간 확인
docker compose logs -f photoview | grep -E "(scan|index|thumbnail)"

# CPU/메모리 사용량 확인
 docker stats photoview

# NAS 트래픽 확인 (선택)
# Activity Monitor → Network 탭

---

⚠️ 트러블슈팅

문제 1: 포트 8000 충돌

# 8000번 사용 중인 프로세스 확인
lsof -i :8000

# PhotoView 포트 변경 (docker-compose.yml 수정)
ports:
  - "8080:80"   # 8080으로 변경

문제 2: NAS 마운트 안 보임

# Docker 볼륨은 컨테이너 기동 시점의 상태를 스냅샷함
# 마운트 후 docker compose restart 필요
docker compose restart photoview

문제 3: 썸네일 생성 너무 느림

# CPU 제한 해제 (docker-compose.yml에 추가)
deploy:
  resources:
    limits:
      cpus: '4'    # 맥미니 코어 수에 맞게
      memory: 8G   # 메모리 제한

문제 4: 권한 오류 (macOS 특유)

# Docker Desktop → Settings → Resources → File sharing
# NAS 마운트 경로가 File sharing 목록에 있는지 확인
# 없으면 추가

---

📁 설치 후 폴더 구조

~/photoview/
├── docker-compose.yml      # Docker 구성
├── database/
│   └── photoview.db        # SQLite DB (사진 메타데이터)
├── cache/
│   └── ...                 # 썸네일/캐시 (자동 생성)
└── .env                    # (선택) 환경변수

---

🔗 관련 문서

• [[01_프로젝트계획서]] — 전체 5단계 계획
• [[03_데이터이전계획]] — 기존 데이터 이전
• [[04_운영관리메뉴얼]] — 일상 운영 절차

---

[!note] 수정이력 | 2026-05-03 18:40, 하늘 (hermes)

• 맥미니 전용 설치 메뉴얼 신규 작성
• OrbStack 권장 (Docker Desktop 대안)
• NAS SMB 마운트 절차 포함
• SQLite 단일 파일 구성 (MariaDB 제거, 가벼움)
• macOS 특유 트러블슈팅 추가