TrueNAS SCALE: Docker 및 Kubernetes 앱 배포 및 관리 완벽 가이드

안녕하세요, 13년차의 서버실 주인장입니다. 홈랩(HomeLab)을 운영하다 보면 NAS에 이것저것 서비스를 올려보고 싶은 욕구가 스멀스멀 올라오잖아요? 저도 처음엔 단순히 파일 저장용으로 시작했는데, Plex(미디어 서버), Nextcloud(개인 클라우드), Home Assistant(스마트 홈 허브) 같은 다양한 앱들을 돌리고 싶어서 고민이 많았습니다.

예전에는 일일이 가상머신(Virtual Machine)을 만들어서 설치하곤 했는데, 관리도 어렵고 자원도 많이 먹더라고요. 그러다 컨테이너(Container) 기술인 Docker(도커)와 Kubernetes(쿠버네티스)를 접하게 됐고, NAS에서 이걸 더 쉽게 쓸 방법이 뭘까 고민하던 차에 TrueNAS SCALE을 만나게 됐습니다. TrueNAS SCALE은 리눅스 기반이라 Docker와 Kubernetes를 네이티브(Native)하게 지원하거든요. 특히 TrueNAS SCALE Docker 환경에서 앱을 배포하고 관리하는 경험은 정말 신세계더라고요.

오늘은 제가 직접 TrueNAS SCALE을 활용해서 Docker와 Kubernetes 앱을 배포하고 관리하면서 겪었던 삽질 경험과 해결 과정, 그리고 효율적인 관리 팁까지 완벽하게 풀어드리려고 합니다. 홈랩에 컨테이너 기반 앱을 올려보고 싶었던 분들이라면 이 글이 큰 도움이 될 거예요!

TrueNAS SCALE 환경에서 Docker 및 Kubernetes 앱 배포의 전체적인 아키텍처를 보여주는 다이어그램입니다.

TrueNAS SCALE, Docker, Kubernetes 핵심 개념 이해하기

본격적인 실전에 들어가기 전에, 우리가 다룰 핵심 기술들이 무엇인지 쉽고 간단하게 짚고 넘어갈 수 있도록, 제가 처음 공부할 때 “이게 뭔 소리야?” 했던 개념들을 멘토처럼 알려드릴게요!

TrueNAS SCALE: 리눅스 기반의 강력한 NAS 운영체제

• TrueNAS SCALE은 오픈소스(Open Source) NAS 운영체제인 TrueNAS의 한 버전입니다. 기존 FreeBSD 기반의 TrueNAS CORE와는 다르게 Debian Linux(데비안 리눅스)를 기반으로 하고 있어요.
• 이 덕분에 컨테이너(Container) 기술인 Docker와 오케스트레이션(Orchestration) 도구인 Kubernetes를 기본적으로 지원하고, 훨씬 더 넓은 범위의 앱 생태계를 활용할 수 있게 됐죠.
• 강력한 파일 시스템인 ZFS(Z File System)를 기반으로 데이터 무결성(Data Integrity)과 유연한 스토리지 관리를 제공하는 건 기본입니다.

Docker (도커): 앱을 컨테이너에 담아 쉽게 배포!

• Docker(도커)는 애플리케이션(Application)과 그 실행에 필요한 모든 요소를 컨테이너라는 독립적인 환경에 패키징(Packaging)하여 배포하고 실행하는 기술입니다. 쉽게 말해, 앱을 하나의 깔끔한 상자에 담아 어디서든 똑같이 실행될 수 있도록 만들어주는 거죠.
• 장점:
  • 이식성(Portability): 어떤 환경에서든 동일하게 작동합니다. “제 컴퓨터에선 되는데?” 하는 말을 들을 일이 줄어들어요.
  • 격리성(Isolation): 각 앱이 서로 영향을 주지 않고 독립적으로 실행됩니다.
  • 효율성(Efficiency): 가상머신보다 가볍고 빠릅니다.

Kubernetes (쿠버네티스): 컨테이너 오케스트레이션의 지휘자

• Kubernetes(쿠버네티스, 줄여서 K8s)는 컨테이너화된 워크로드(Workload)와 서비스를 자동으로 배포하고, 스케일링(Scaling)하며, 관리해주는 오픈소스 시스템입니다. Docker 컨테이너가 많아지면 이걸 효율적으로 관리하는 게 정말 어려워지거든요. 이때 K8s가 마치 지휘자처럼 여러 컨테이너를 조율해줍니다.
• TrueNAS SCALE Kubernetes 환경에서는 TrueNAS의 ‘Apps’ 기능을 통해 Helm Chart(헬름 차트) 기반의 Kubernetes 앱을 쉽게 배포할 수 있어요.
• NAS 앱 배포를 자동화하고 안정성을 높이는 데 아주 효과적이죠.

Dockge (닥지): Docker Compose를 위한 웹 UI

• TrueNAS SCALE의 내장 Apps 기능도 훌륭하지만, Docker Compose(도커 컴포즈) 파일을 직접 관리하는 데 익숙한 분들에게는 조금 답답할 수 있어요. 이때 Dockge(닥지)가 구원투수로 등장합니다!
• Dockge는 Docker Compose 파일을 웹 UI(User Interface)를 통해 생성, 편집, 배포, 모니터링할 수 있게 해주는 경량 도구입니다. 제가 직접 써보니 Docker Compose를 활용한 컨테이너 관리가 훨씬 편하더라고요.

TrueNAS SCALE에서 Docker 및 Kubernetes 앱 실전 배포

자, 이제 이론은 충분히 봤으니 직접 한번 해봐야죠! 제가 실제로 홈랩에서 앱을 배포하는 과정을 보여드릴게요. TrueNAS SCALE의 ‘Apps’ 기능을 이용하는 방법과 Dockge를 활용하는 두 가지 방법을 모두 알려드리겠습니다.

1. TrueNAS SCALE 내장 ‘Apps’ 기능 활용하기 (Kubernetes 기반)

TrueNAS SCALE은 자체적으로 Kubernetes 클러스터를 내장하고 있어서 ‘Apps’ 메뉴를 통해 다양한 앱을 손쉽게 배포할 수 있어요. 주로 Helm Chart(헬름 차트) 기반의 앱들이 제공됩니다.

1. Apps 기능 활성화 및 스토리지 풀 선택:
   • TrueNAS SCALE 웹 UI에 접속합니다.
   • 좌측 메뉴에서 ‘Apps’를 클릭합니다.
   • ‘Settings’ 탭으로 이동하여 ‘Choose Pool’에서 앱 데이터를 저장할 ZFS 스토리지 풀(Storage Pool)을 선택합니다. 저는 보통 ‘ix-applications’라는 데이터셋(Dataset)이 자동으로 생성되도록 합니다.
   • ‘Save’를 눌러 설정을 저장합니다.
2. 앱 검색 및 설치:
   • ‘Available Applications’ 탭으로 돌아와 원하는 앱을 검색해요. 예를 들어 ‘Plex’를 검색해 볼까요?
   • Plex 앱을 선택하고 ‘Install’을 클릭합니다.
   • 설치 마법사(Wizard)가 나타나는데, 여기서 앱 이름, Persistent Volume(영구 볼륨), 네트워크 설정, 환경 변수(Environment Variables) 등을 설정할 수 있어요. 특히 볼륨 설정은 앱 데이터가 저장될 위치를 지정하는 중요한 부분이니 신중하게 설정해야 합니다.
   • 필요한 설정을 마친 후 ‘Install’을 클릭하면 앱 배포가 시작됩니다.
3. 배포된 앱 확인:
   • ‘Installed Applications’ 탭에서 배포된 앱의 상태를 확인할 수 있어요. ‘Deploying’에서 ‘Active’로 바뀌면 정상적으로 실행 중인 것입니다.
   • 앱 옆의 ‘Web UI’ 버튼을 클릭하여 해당 앱의 웹 인터페이스에 접속할 수 있습니다.

2. Dockge를 활용하여 Docker Compose 앱 배포하기

TrueNAS SCALE의 Apps 기능도 좋지만, 저는 Docker Compose 파일로 직접 컨테이너 설정을 제어하는 걸 더 선호하는 편입니다. 이때 Dockge TrueNAS 설치가 정말 유용하더라고요. Dockge는 Docker Compose 파일을 웹 UI에서 쉽게 관리할 수 있게 해줍니다. 먼저 Dockge부터 설치해봅시다!

2.1. Dockge 설치

Dockge는 Docker 컨테이너로 실행되는데, TrueNAS SCALE의 Shell(쉘)을 통해 Docker 명령어를 직접 입력하여 설치할 수 있어요.

1. TrueNAS SCALE Shell 접속:
   • TrueNAS SCALE 웹 UI에서 ‘System Settings’ > ‘Shell’로 이동합니다.
2. Dockge 설치 스크립트 실행:

   다음 명령어를 입력하여 Dockge를 설치합니다. 이 명령어는 Docker Compose를 이용해 Dockge 컨테이너를 실행하고, 필요한 볼륨과 네트워크를 설정해줍니다. 저는 주로 /mnt/pool_name/appdata/dockge 경로에 데이터를 저장합니다.

   mkdir -p /mnt/pool_name/appdata/dockge
   cd /mnt/pool_name/appdata/dockge
   
   curl -L https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml -o compose.yaml
   
   docker compose up -d
   

   여기서 pool_name은 여러분의 ZFS 스토리지 풀 이름으로 바꿔주세요. 예를 들어 /mnt/tank/appdata/dockge 처럼요.

3. Dockge 웹 UI 접속:

   설치가 완료되면 웹 브라우저에서 http://[TrueNAS_IP]:5001 (기본 포트)로 접속하여 Dockge 웹 UI를 확인할 수 있어요. 처음 접속 시 관리자 계정을 설정하게 됩니다.

2.2. Dockge를 이용한 Docker Compose 앱 배포

Dockge에 접속했다면 이제 원하는 Docker Compose 앱을 배포해봅시다. 저는 간단한 Nginx 웹 서버를 예시로 들어볼게요.

1. 새로운 스택(Stack) 생성:
   • Dockge UI에서 ‘Stacks’ > ‘New Stack’을 클릭합니다.
   • 스택 이름을 입력하고, Docker Compose YAML 파일을 붙여넣어요.
2. Docker Compose YAML 작성 예시 (Nginx):

   version: '3.8'
   services:
     nginx:
       image: nginx:latest
       container_name: my-nginx
       restart: unless-stopped
       ports:
         - "80:80"
       volumes:
         - /mnt/pool_name/appdata/nginx/html:/usr/share/nginx/html
         - /mnt/pool_name/appdata/nginx/conf:/etc/nginx/conf.d
   

   위 YAML 파일은 Nginx 컨테이너를 실행하고, 호스트의 80번 포트를 컨테이너의 80번 포트에 연결하며, 데이터를 저장할 볼륨을 설정합니다. 역시 pool_name은 여러분의 스토리지 풀 이름으로 바꿔주세요.

3. 스택 배포:
   • YAML 파일을 붙여넣고 ‘Deploy’ 버튼을 클릭하면 Dockge가 Docker Compose 명령어를 실행하여 컨테이너를 배포해요.
   • 배포 상태와 로그를 실시간으로 확인할 수 있어서 문제 발생 시 디버깅(Debugging)하기 정말 편하더라고요.

Dockge 웹 UI에서 Docker Compose 스택을 생성하고 설정하는 화면입니다. YAML 파일 편집과 배포가 한눈에 들어와서 편리하죠.

⚠️ 삽질 경험 & 트러블슈팅 가이드

13년차 엔지니어 생활에서 느낀 건, 새로운 기술을 도입할 때 삽질은 숙명이라는 거예요. TrueNAS SCALE에서 컨테이너 앱을 배포하면서 저도 몇 번이나 “아, 이거 왜 안 되지?” 하면서 머리를 쥐어뜯었거든요. 그 경험을 바탕으로 여러분이 겪을 만한 문제와 해결책을 공유합니다.

1. 스토리지 권한 문제 (Permissions Issue)

이거 진짜 제일 많이 겪는 문제예요. 특히 Docker 컨테이너가 TrueNAS의 ZFS 데이터셋에 접근할 때 권한이 없어서 파일을 생성하거나 읽지 못하는 경우가 허다하거든요. 컨테이너 내부의 프로세스는 특정 사용자(User)와 그룹(Group)으로 실행되는데, 이 사용자에게 ZFS 데이터셋에 대한 쓰기 권한이 없어서 생기는 문제예요.

• 해결책:
  1. ACL(Access Control List) 설정: TrueNAS 웹 UI에서 해당 데이터셋의 ‘Edit ACL’을 통해 ‘Default ACL’을 설정해주는 게 가장 깔끔합니다. ‘OPEN’ 프리셋을 적용하고, ‘Apply permissions recursively’를 체크하여 하위 폴더까지 적용해줘요.
  2. Shell에서 권한 변경: 급하게 테스트할 때는 Shell에서 chmod와 chown 명령어를 사용하기도 합니다.

     # 소유자를 root:wheel로 변경 (컨테이너가 보통 root로 실행될 때)
     sudo chown -R root:wheel /mnt/pool_name/appdata/your_app
     
     # 모든 사용자에게 읽기/쓰기/실행 권한 부여 (주의: 보안에 취약할 수 있음)
     sudo chmod -R 777 /mnt/pool_name/appdata/your_app
     

     하지만 chmod 777은 보안상 좋지 않으니, 컨테이너가 필요로 하는 최소한의 권한을 부여하는 것을 권장합니다. 보통 PUID/PGID(Process User ID/Group ID) 환경 변수를 통해 컨테이너 내부 사용자 ID를 지정하는 방식으로 해결하더라고요.

2. 네트워크 설정 및 포트 충돌

컨테이너 앱이 외부와 통신하려면 네트워크 설정이 중요한데, 특히 포트(Port) 충돌이 자주 발생해요.

• 문제: 이미 TrueNAS 자체 서비스(예: SMB, SSH)나 다른 컨테이너가 사용 중인 포트를 앱이 사용하려고 할 때 생깁니다.
• 해결책:
  • 사용 가능한 포트 확인: netstat -tulnp 명령어를 Shell에서 실행하여 현재 사용 중인 포트를 확인해요.
  • 포트 변경: 앱 설정이나 Docker Compose YAML 파일에서 호스트 포트를 다른 사용 가능한 포트로 변경합니다. 예를 들어 Nginx의 80번 포트가 충돌한다면 "8080:80"처럼 변경할 수 있어요.
  • Host Network 사용 시 주의: TrueNAS SCALE의 Apps에서는 ‘Host Network’ 옵션을 제공하는데, 이는 컨테이너가 호스트의 네트워크 스택을 직접 사용하게 하여 성능상 이점이 있지만, 포트 충돌 가능성이 더 높아집니다. 신중하게 사용해야 해요.

3. 앱 업데이트 후 데이터 유실/오류

컨테이너 앱을 업데이트하다가 데이터가 날아가거나 앱이 실행되지 않는 경험, 해보셨나요? 😭 저도 예전에 한번 겪고 식겁한 적이 있습니다.

• 해결책:
  • 백업(Backup) 필수: 업데이트 전에는 항상 중요한 데이터를 백업해둬야 해요. ZFS 스냅샷(Snapshot) 기능을 활용하면 매우 편리하거든요.
  • 볼륨(Volume) 분리: 컨테이너 이미지와 데이터를 저장하는 볼륨을 분리하여 사용하면, 앱을 업데이트하거나 다시 배포해도 데이터는 안전하게 유지됩니다. Dockge의 Docker Compose YAML 예시에서도 볼륨을 명시적으로 분리했죠.
  • 업데이트 전 로그 확인: 새로운 버전의 변경 사항(Changelog)을 미리 확인하여 호환성 문제를 예측하고 대비해요.

✅ 배포된 앱 검증 및 결과 확인

수많은 삽질 끝에 드디어 앱 배포에 성공했어요! 이제 앱이 제대로 작동하는지 확인해봐야죠. 저는 주로 다음 세 가지를 확인합니다.

1. 웹 UI 접속 확인: 배포한 앱의 웹 인터페이스에 접속하여 정상적으로 화면이 뜨고 로그인, 기능 사용이 가능한지 확인해요. 예를 들어 Nginx라면 웹 브라우저에서 TrueNAS IP로 접속했을 때 기본 페이지가 보여야 하죠.
2. 로그 확인: 앱이 제대로 작동하지 않을 때는 로그를 확인하는 게 가장 중요합니다.
   • TrueNAS SCALE Apps의 경우: ‘Installed Applications’에서 해당 앱을 선택하고 ‘Logs’ 탭을 확인해요.
   • Dockge를 통해 배포한 Docker Compose 앱의 경우: Dockge UI에서 해당 스택을 선택하면 실시간 로그를 확인할 수 있어요. 또는 TrueNAS Shell에서 docker logs [컨테이너_이름] 명령어를 사용합니다.
3. 리소스 모니터링: TrueNAS SCALE 대시보드에서 CPU, RAM, 네트워크 사용량 등을 확인하여 앱이 과도하게 리소스를 소모하고 있지 않은지 점검해요. 특히 RAM 사용량은 컨테이너 앱이 많아질수록 중요해지거든요.

성공적으로 배포된 Plex 미디어 서버의 대시보드 화면입니다. TrueNAS SCALE 위에서 컨테이너 앱들이 안정적으로 작동하는 것을 확인할 수 있습니다.

🎉 마무리: TrueNAS SCALE로 홈랩을 더욱 강력하게!

오늘은 TrueNAS SCALE에서 Docker와 Kubernetes 앱을 배포하고 관리하는 완벽 가이드를 함께 살펴봤습니다. 처음엔 좀 복잡하게 느껴질 수도 있지만, 한번 제대로 세팅해두면 정말 편리하고 강력한 홈랩 환경을 구축할 수 있어요.

TrueNAS SCALE의 내장 ‘Apps’ 기능으로 Kubernetes 기반의 안정적인 앱 배포를 경험하고, Dockge TrueNAS 설치를 통해 Docker Compose 파일을 직접 제어하며 유연하게 컨테이너 관리를 하는 두 가지 방법을 모두 알려드렸는데요. 저는 개인적으로 Dockge를 통한 Docker Compose 관리가 훨씬 손에 익고, 제어권이 많아서 좋더라고요. 하지만 초보자분들이나 복잡한 설정 없이 바로 사용하고 싶다면 TrueNAS Apps도 훌륭한 선택지입니다.

이런 삽질과 학습 과정을 통해 저의 NAS 앱 배포 경험치도 한 단계 올라간 것 같아요. 여러분도 저처럼 TrueNAS SCALE을 활용해서 나만의 강력한 서버실을 만들어보세요. 다음번에는 Ingress(인그레스, 외부 트래픽 진입점) 설정이나 Persistent Volume(영구 볼륨)의 고급 활용법에 대해 다뤄보면 어떨까 싶네요!

TrueNAS SCALE에서 앱을 배포하는 두 가지 주요 방법, 내장 Apps와 Dockge를 통한 Docker Compose 활용법을 비교한 요약입니다.