[NAS] TrueNAS SCALE 앱 배포: Docker 컨테이너부터 관리까지

목차

• NAS가 단순 저장소였던 시대는 끝났습니다
• TrueNAS SCALE 앱 시스템이 바뀐 이유
• 시작 전 준비사항 체크
• TrueNAS SCALE 앱 카탈로그에서 첫 번째 앱 설치하기
• Docker 컨테이너 직접 배포하기 (Custom App)
• 환경 변수와 네트워크 설정 팁
• ⚠️ 트러블슈팅: 자주 겪는 문제들
• 문제 1: 앱이 Deploying 상태에서 멈춤
• 문제 2: 볼륨 마운트 권한 오류
• 문제 3: 포트 충돌
• TrueNAS SCALE 앱 관리 및 업데이트
• ✅ 실전 구성: 제 홈랩 앱 운영 사례
• 마무리: TrueNAS SCALE 앱 배포, 이렇게 시작하세요

NAS가 단순 저장소였던 시대는 끝났습니다

홈랩을 운영하다 보면 어느 순간 이런 생각이 드시지 않나요? "NAS에 데이터만 넣어두기엔 너무 아깝다." 저도 처음엔 그냥 파일 서버로 쓰다가, 어느 날 Plex를 띄워보고 나서 생각이 완전히 바뀌었거든요. 그 이후로 TrueNAS SCALE 위에서 십수 개의 서비스를 돌리고 있습니다.

근데 솔직히 말씀드리면, 처음에 TrueNAS SCALE 앱 시스템을 접했을 때 꽤 헷갈렸어요. 버전마다 배포 방식이 달라지고, 한글 자료도 많지 않아서 삽질을 꽤 했거든요. 이번 글에서는 제가 직접 겪어온 경험을 바탕으로, TrueNAS SCALE에서 앱을 배포하고 관리하는 방법을 처음부터 끝까지 정리해 드리겠습니다.

TrueNAS SCALE 위에서 여러 컨테이너 앱이 동작하는 홈랩 전체 아키텍처. 스토리지, 네트워킹, 앱 레이어가 통합된 모습입니다.

TrueNAS SCALE 앱 시스템이 바뀐 이유

여기서 중요한 역사 이야기를 하나 해야 할 것 같아요. TrueNAS SCALE의 앱 시스템은 버전을 거치면서 꽤 큰 변화가 있었거든요.

초기 버전(Angelfish, Bluefin, Cobia 등)에서는 K3s(경량 쿠버네티스)를 기반으로 앱을 운영했습니다. 쿠버네티스를 쓴다니까 좋아 보이긴 했는데, 일반 홈랩 사용자 입장에서는 진입 장벽이 꽤 높았어요. Helm 차트 구조도 이해해야 하고, 리소스 관리가 복잡하다는 불만도 많았고요.

그래서 iXsystems는 Electric Eel(24.10) 버전부터 TrueNAS SCALE 앱 시스템을 Docker Compose 기반으로 전면 바꿨습니다. 쿠버네티스를 걷어내고 훨씬 직관적인 Docker Compose 방식을 채택한 거죠. 솔직히 처음엔 "아니 왜 바꾸는 거야"라고 생각했는데, 써보니 훨씬 낫더라고요.

• 이전(~Dragonfish): K3s + Helm Chart 기반, TrueCharts 커뮤니티 카탈로그 의존도 높음
• 이후(Electric Eel~): Docker Compose 기반, 공식 카탈로그 + 커스텀 컨테이너 지원

이 글은 Electric Eel 이후의 Docker Compose 기반 앱 시스템을 중심으로 설명합니다. 혹시 구버전 사용 중이시라면 업그레이드를 먼저 하시길 권장합니다.

시작 전 준비사항 체크

본격적으로 TrueNAS SCALE 앱 배포에 들어가기 전에 확인해야 할 것들이 있어요. 저도 이걸 안 하고 바로 들어갔다가 중간에 막혀서 처음부터 다시 한 경험이 있거든요 😅

1. 풀(Pool) 설정 확인: 앱 데이터를 저장할 ZFS 풀이 생성되어 있어야 합니다. 저는 SSD 별도 풀을 만들어서 앱 전용으로 씁니다.
2. Apps 전용 풀 지정: TrueNAS SCALE에서 Apps 탭으로 이동하면, 앱 데이터를 저장할 풀을 처음 한 번 지정하게 돼 있어요. 나중에 바꾸기 귀찮으니 처음에 잘 골라두세요.
3. 네트워크 설정: 외부에서 접근이 필요한 앱이라면, 공유기 포트 포워딩이나 Reverse Proxy(리버스 프록시) 설정도 미리 생각해두면 좋습니다.
4. TrueNAS SCALE 버전: 앞서 말씀드린 것처럼, 가능하면 Electric Eel(24.10) 이상으로 업그레이드하고 시작하세요.

TrueNAS SCALE 앱 카탈로그에서 첫 번째 앱 설치하기

준비가 됐다면 이제 실전입니다! TrueNAS SCALE 웹 UI 왼쪽 메뉴에서 Apps를 클릭하세요. 처음 접속하면 앱 풀(pool)을 선택하라고 나옵니다. 앞서 준비한 풀을 선택하면 돼요.

앱 화면으로 들어오면 Discover Apps 버튼이 보입니다. 여기서 공식 카탈로그에 등록된 앱들을 검색하고 설치할 수 있어요. Plex, Nextcloud, Jellyfin, Home Assistant 같은 인기 홈랩 앱들이 대부분 등록되어 있습니다.

예시로 Jellyfin(미디어 서버)을 설치해볼게요.

1. Discover Apps에서 "Jellyfin" 검색
2. 앱 카드 클릭 → Install 버튼 클릭
3. 설정 화면에서 주요 항목 입력:
   • Application Name: jellyfin (기본값 그대로)
   • Network Configuration: 포트 번호 설정 (기본 8096)
   • Storage Configuration: 미디어 파일이 있는 데이터셋 경로 지정
4. Install 클릭 후 배포 완료 대기

설치가 완료되면 앱 목록에 Jellyfin이 나타나고, http://NAS-IP:8096으로 접속할 수 있어요. 드디어 됐다! 라는 느낌이 이때 오더라고요 🎉

TrueNAS SCALE Apps 탭의 카탈로그 화면. Discover Apps에서 원하는 앱을 검색하고 GUI로 간편하게 설치할 수 있습니다.

Docker 컨테이너 직접 배포하기 (Custom App)

카탈로그에 없는 앱을 써야 할 때가 있죠. 저도 특정 오픈소스 툴을 올리고 싶은데 카탈로그에 없을 때, 직접 Docker 이미지를 지정해서 배포하는 방법을 씁니다. Docker on TrueNAS를 활용하는 방식이에요.

Discover Apps 화면 오른쪽 위를 보면 Custom App 버튼이 있습니다. 이걸 누르면 Docker Compose 방식으로 직접 컨테이너를 정의할 수 있는 화면이 나와요.

예시로 Uptime Kuma(서비스 모니터링 앱)를 커스텀 앱으로 배포해볼게요.

# Custom App 설정에서 사용하는 Docker Compose 예시
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    ports:
      - "3001:3001"
    volumes:
      - /mnt/pool/apps/uptime-kuma:/app/data
    restart: unless-stopped

TrueNAS SCALE의 Custom App UI에서는 이걸 GUI 폼으로 입력할 수 있어요. 직접 YAML을 쓰는 방식도 지원되고, 폼 형태로도 입력 가능합니다.

핵심 입력 항목들은 이렇습니다:

항목	설명	예시
Image Repository	Docker Hub 이미지 이름	louislam/uptime-kuma
Image Tag	버전 태그	latest 또는 1.23.x
Container Port	컨테이너 내부 포트	3001
Node Port	호스트에서 접근할 포트	3001
Host Path	TrueNAS 데이터셋 경로	/mnt/pool/apps/uptime-kuma
Mount Path	컨테이너 내부 마운트 경로	/app/data

💡 팁: 볼륨 경로는 반드시 미리 ZFS 데이터셋으로 만들어두고 마운트하는 게 좋습니다. 그냥 디렉토리 경로를 쓰면 나중에 스냅샷 관리가 안 되거든요. 이거 처음에 몰라서 나중에 다 옮긴 적이 있습니다 ㅎㅎ.

환경 변수와 네트워크 설정 팁

컨테이너를 배포할 때 환경 변수(Environment Variable) 설정이 필요한 경우가 많아요. 예를 들어 데이터베이스 비밀번호, API 키 같은 것들이요.

Custom App 설정 화면에서 Environment Variables 섹션을 찾으면 Key-Value 형태로 추가할 수 있습니다.

# 환경 변수 예시 (Nextcloud 같은 경우)
MYSQL_DATABASE=nextcloud
MYSQL_USER=ncuser
MYSQL_PASSWORD=your_secure_password
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=admin_password

네트워크 관련해서 한 가지 더 말씀드리면, TrueNAS SCALE에서 여러 앱이 서로 통신해야 할 때(예: 웹 앱 + DB 컨테이너) 같은 Docker 네트워크에 묶어야 해요. Custom App에서 Network Configuration 섹션에서 네트워크를 지정할 수 있습니다. 이 부분은 처음엔 좀 헷갈릴 수 있는데, 같은 앱 스택이라면 동일한 사용자 정의 네트워크를 사용하면 돼요.

⚠️ 트러블슈팅: 자주 겪는 문제들

13년 동안 인프라 일을 하면서 깨달은 건, 문서대로 안 되는 게 정상이라는 거예요 ㅎㅎ. TrueNAS SCALE 앱 배포하면서 자주 만나는 문제들과 해결법을 공유합니다.

문제 1: 앱이 Deploying 상태에서 멈춤

가장 흔한 문제예요. 배포 눌렀는데 한참 동안 Deploying 상태에서 안 바뀌는 경우.

원인 대부분은 이미지 풀(pull) 실패입니다. 이미지 이름이 틀렸거나, NAS가 인터넷에 제대로 연결 안 됐을 때 주로 발생해요.

# TrueNAS Shell에서 컨테이너 로그 확인
docker logs [컨테이너_이름]

# 이미지가 제대로 받아졌는지 확인
docker images | grep [앱_이름]

문제 2: 볼륨 마운트 권한 오류

앱은 뜨는데 데이터를 못 쓰는 경우가 있어요. 특히 컨테이너가 특정 UID로 실행되는데, 마운트한 경로의 소유자가 다를 때 발생합니다.

# TrueNAS Shell에서 권한 확인 및 수정
ls -la /mnt/pool/apps/uptime-kuma

# 필요하다면 소유자 변경 (999는 예시 UID, 앱마다 다름)
chown -R 999:999 /mnt/pool/apps/uptime-kuma

💡 팁: Docker Hub의 해당 이미지 문서에 어떤 UID로 실행되는지 나와 있는 경우가 많아요. 미리 확인하고 데이터셋 권한을 맞춰두면 삽질을 줄일 수 있습니다.

문제 3: 포트 충돌

"이미 사용 중인 포트"라는 오류가 뜨는 경우요. 앱들이 기본 포트가 겹칠 때 발생합니다. 예를 들어 여러 웹 앱이 다 80번 포트를 쓰려 하면 충돌이 나죠.

해결책은 단순합니다. 앱 설치 시 Node Port를 겹치지 않게 다른 번호로 바꿔주면 돼요. 저는 개인적으로 앱별로 포트 번호를 스프레드시트에 정리해두고 쓰고 있습니다. 처음엔 귀찮아 보여도, 앱이 10개 이상 넘어가면 이게 필수예요.

TrueNAS SCALE 앱 관리 및 업데이트

설치하고 끝이 아니죠. 앱 관리도 중요합니다. TrueNAS SCALE에서 설치된 앱의 업데이트는 Apps 탭 → Installed 화면에서 할 수 있어요.

업데이트 가능한 앱이 있으면 배지(badge)가 표시되고, Update All 버튼으로 한 번에 업데이트도 가능합니다. 근데 저는 한 번에 다 올리기보다는, 중요한 앱은 하나씩 올리고 확인하는 편이에요. 한 번에 다 올렸다가 뭔가 깨지면 어디서 문제가 생긴 건지 찾기 어렵거든요.

앱 데이터 백업은 ZFS 스냅샷을 활용하는 게 최고입니다. 앱 데이터를 담은 데이터셋에 정기 스냅샷을 걸어두면, 앱이 망가졌을 때 스냅샷으로 롤백이 가능해요. 이게 TrueNAS SCALE을 쓰는 가장 큰 이유 중 하나라고 생각합니다.

TrueNAS SCALE Apps의 Installed 탭. 실행 중인 앱 상태, 업데이트 가능 여부, 리소스 사용량을 한눈에 확인할 수 있습니다.

✅ 실전 구성: 제 홈랩 앱 운영 사례

참고로 현재 제가 TrueNAS SCALE 위에서 돌리고 있는 주요 앱들을 공유할게요. 비슷한 구성을 계획하시는 분들께 도움이 될 것 같아서요.

앱 이름	용도	설치 방법
Jellyfin	미디어 서버 (영화, 음악)	공식 카탈로그
Nextcloud	개인 클라우드 스토리지	공식 카탈로그
Home Assistant	스마트홈 허브	공식 카탈로그
Uptime Kuma	서비스 모니터링	Custom App
Vaultwarden	비밀번호 관리자	Custom App
Nginx Proxy Manager	리버스 프록시 + SSL	Custom App

모두 ZFS 데이터셋에 데이터를 저장하고, 매일 새벽 3시에 스냅샷이 자동으로 찍히도록 설정해뒀습니다. 덕분에 앱 업데이트 실패나 설정 꼬임 같은 상황에서도 걱정 없이 복구할 수 있어요. 실제로 Home Assistant 업데이트 후 통합 설정이 날아갔을 때 스냅샷으로 5분 만에 복구한 적도 있습니다 😅

현재 운영 중인 홈랩의 앱 구성 요약. TrueNAS SCALE 위에서 미디어, 클라우드, 모니터링, 보안 앱들이 유기적으로 연동되는 모습입니다.

마무리: TrueNAS SCALE 앱 배포, 이렇게 시작하세요

오늘 다룬 내용을 간단히 정리해볼게요.

• ✅ TrueNAS SCALE은 Electric Eel(24.10)부터 Docker Compose 기반 앱 시스템으로 전환됨
• ✅ 공식 카탈로그 앱은 GUI로 손쉽게 설치 가능
• ✅ 카탈로그에 없는 앱은 Custom App 기능으로 Docker 이미지 직접 지정 배포
• ✅ 볼륨은 반드시 ZFS 데이터셋으로 분리해서 관리할 것
• ✅ 스냅샷 정책을 함께 설정해두면 백업/복구가 정말 편함

처음 TrueNAS SCALE 앱 시스템을 접하면 설정 항목이 많아서 막막할 수 있어요. 근데 한 번 익숙해지면 정말 편합니다. 스토리지와 앱을 같은 플랫폼에서 관리한다는 게 이렇게 편할 줄 몰랐다는 생각이 드실 거예요.

다음 글에서는 Nginx Proxy Manager와 Let's Encrypt를 이용한 HTTPS 설정을 다룰 예정입니다. 외부에서 도메인으로 안전하게 접근하는 방법인데, 홈랩을 한 단계 업그레이드하고 싶은 분들께 유용할 거예요. 이전 글에서 다뤘던 ZFS 데이터셋 구성과 함께 보시면 더 도움이 됩니다.

궁금한 점이 있으면 댓글로 남겨주세요. 같이 삽질하며 발전하는 홈랩 라이프, 응원합니다! 🎉

📚 함께 읽으면 좋은 글

• NAS RAID 설정 트러블슈팅: 문제 진단부터 데이터 복구까지 완벽 가이드
• Synology Docker 완벽 가이드: 컨테이너 관리부터 실전 운영까지
• TrueNAS SCALE SMB 공유 설정 및 성능 최적화 완벽 가이드