설치 및 첫 번째 부팅

이 문서는 운영자가 베어 Linux GPU 워크스테이션에서 root 관리자 계정이 있는 LabPod 서버를 실행하기까지의 과정을 안내합니다. 10~15분 정도 소요되며, 사용자가 처음으로 워크스페이스를 생성할 때 이미지 풀 시간이 추가됩니다.

시작 전에 요구사항을 먼저 훑어보세요. 설치 프로그램의 --check 모드가 대부분의 요구사항을 자동으로 확인해 줍니다.

필요한 것

• 지원되는 Linux 호스트: Ubuntu/Debian (apt) 또는 Fedora/RHEL/Rocky (dnf).
• 해당 호스트의 sudo / root 권한.
• 배포판 패키지 저장소 및 NVIDIA container-toolkit 저장소에 대한 네트워크 접근 (설치 프로그램이 Podman과 GPU 툴킷을 자동으로 추가합니다).
• GPU 워크스페이스의 경우: 드라이버가 이미 설치된 NVIDIA GPU. 설치 프로그램은 NVIDIA Container Toolkit과 CDI 스펙을 구성하지만, GPU 드라이버 자체는 설치하지 않습니다.

스크립트로 설치

LabPod는 하나의 공개 설치 스크립트를 제공합니다. 단순한 앱 설치 프로그램이 아니라 호스트 설정 스크립트입니다. Podman과 루트리스 의존성을 설치하고 NVIDIA 툴킷 저장소를 추가하며, CDI 스펙을 생성하고 labpod 바이너리와 systemd 유닛을 설치합니다. 이 스크립트는 멱등성이 있어 이미 구성된 항목은 건너뛰고 다시 실행해도 안전합니다.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

# 드라이 런: 누락된 항목을 보고하고 아무것도 변경하지 않음
curl -fsSL https://labpod.ai/install.sh | sudo bash -s -- --check

# 실제 설치 (최신 릴리스)
curl -fsSL https://labpod.ai/install.sh | sudo bash

# 고정된 버전으로 설치
curl -fsSL https://labpod.ai/install.sh | sudo bash -s -- --version v0.x.y

# 호스트 사전 요구사항만 설치하고 labpod 서비스는 건너뜀
curl -fsSL https://labpod.ai/install.sh | sudo bash -s -- --skip-app

# Run these as root
# 드라이 런: 누락된 항목을 보고하고 아무것도 변경하지 않음
curl -fsSL https://labpod.ai/install.sh | bash -s -- --check

# 실제 설치 (최신 릴리스)
curl -fsSL https://labpod.ai/install.sh | bash

# 고정된 버전으로 설치
curl -fsSL https://labpod.ai/install.sh | bash -s -- --version v0.x.y

# 호스트 사전 요구사항만 설치하고 labpod 서비스는 건너뜀
curl -fsSL https://labpod.ai/install.sh | bash -s -- --skip-app

유용한 설치 옵션:

옵션	설명
--check	드라이 런: 변경될 내용만 보고하고 아무것도 바꾸지 않습니다
--skip-socket	대상 사용자의 podman.socket 활성화를 건너뜁니다
--skip-app	호스트 사전 요구사항만 설치하고 labpod 바이너리와 서비스는 건너뜁니다
--skip-backup	업그레이드 시 자동 pre-upgrade DB 백업을 건너뜁니다
--bin <path>	지원 또는 복구 상황에서 제공된 로컬 labpod 바이너리를 설치합니다
--admin-password-file <path>	root LabPod 비밀번호를 비대화식으로 부트스트랩합니다
--gpu-sharing-lib <path>	기존 HAMi/libvgpu 호환 라이브러리를 설치합니다
--with-hami	Podman으로 HAMi 공유 라이브러리를 빌드해 분할 GPU를 활성화합니다 (기본 OFF)
--uninstall	설정, 데이터, 라이선스, 사용자 계정은 유지하고 LabPod 관리 바이너리, 유닛, 생성 자산을 제거합니다
--uninstall --purge	DB, 백업, 라이선스 등 /etc/labpod와 /var/lib/labpod 데이터도 함께 제거합니다. 연구자 계정의 홈과 work 데이터는 제거하지 않습니다
--uninstall --check	제거 dry-run입니다. 제거될 항목만 보고합니다

릴리스 tarball로 설치

변경 관리 정책상 curl | bash를 사용할 수 없다면 GitHub Release 자산을 먼저 다운로드하고 검증한 뒤 tarball을 풀어서 패키지에 포함된 설치 프로그램을 실행하세요:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

BASE="https://github.com/LabPod/labpod/releases/latest/download"

curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz"
curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz.sig"
curl -fLO "${BASE}/SHA256SUMS"

sha256sum -c SHA256SUMS

cat > labpod-artifact-pub.pem <<'EOF'
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEki5c/1B4iOqb16m6ljKHjnbbq5EP
D8mP4mNRCYrqniXLDAkDFbpGaMw6WqPBiCQUVqyvDzyL+pADdJTAdxcUSw==
-----END PUBLIC KEY-----
EOF

openssl dgst -sha256 \
  -verify labpod-artifact-pub.pem \
  -signature labpod-linux-x86_64.tar.gz.sig \
  labpod-linux-x86_64.tar.gz

mkdir labpod-release
tar -xzf labpod-linux-x86_64.tar.gz -C labpod-release

sudo bash labpod-release/scripts/install.sh

# Run these as root
BASE="https://github.com/LabPod/labpod/releases/latest/download"

curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz"
curl -fLO "${BASE}/labpod-linux-x86_64.tar.gz.sig"
curl -fLO "${BASE}/SHA256SUMS"

sha256sum -c SHA256SUMS

cat > labpod-artifact-pub.pem <<'EOF'
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEki5c/1B4iOqb16m6ljKHjnbbq5EP
D8mP4mNRCYrqniXLDAkDFbpGaMw6WqPBiCQUVqyvDzyL+pADdJTAdxcUSw==
-----END PUBLIC KEY-----
EOF

openssl dgst -sha256 \
  -verify labpod-artifact-pub.pem \
  -signature labpod-linux-x86_64.tar.gz.sig \
  labpod-linux-x86_64.tar.gz

mkdir labpod-release
tar -xzf labpod-linux-x86_64.tar.gz -C labpod-release

bash labpod-release/scripts/install.sh

특정 버전을 고정해서 설치하려면 BASE를 https://github.com/LabPod/labpod/releases/download/v0.1.0 같은 버전별 릴리스 URL로 설정합니다. 설치 옵션은 스크립트 경로 뒤에 그대로 붙일 수 있습니다. 예를 들어 sudo bash labpod-release/scripts/install.sh --check를 실행할 수 있습니다.

스크립트가 수행하는 작업:

1. OS를 감지합니다 (apt vs dnf).
2. podman과 루트리스 의존성을 설치합니다 (누락된 경우에만).
3. 대상 사용자의 /etc/subuid 및 /etc/subgid 항목을 추가합니다 (누락된 경우에만).
4. 로그아웃 후에도 루트리스 컨테이너가 유지되도록 사용자에게 systemd linger를 활성화합니다.
5. 사용자의 podman.socket을 활성화합니다.
6. 환경을 검증합니다: cgroup 모드 (v2 권장; v1은 저하된 모드로 실행), 사용자 네임스페이스 등.
7. NVIDIA 호스트에서는 GPU 스택(NVIDIA Container Toolkit + CDI)을 설치합니다. 분할 GPU 공유(HAMi/libvgpu)는 기본 OFF이며, --with-hami를 전달하면 빌드하고 활성화합니다.
8. labpod 바이너리를 /usr/local/bin/labpod에 설치하고, /etc/labpod/labpod.env를 시드하고, labpod.service를 등록합니다.
9. /opt/labpod/inject 아래에 워크스페이스 헬퍼 파일(tmux, labpod-monitor, terminfo, home skeleton 파일)을 설치합니다.
10. 누락된 기본 환경 키를 채우고, 설정된 경우 root가 관리하는 공유 이미지 저장소를 준비합니다. 각 연구자는 워크스페이스를 시작하기 전에 자신의 루트리스 이미지 사본을 받습니다.
11. /var/lib/labpod/backups/에 일별 SQLite 스냅샷을 위한 labpod-backup.timer / labpod-backup.service를 설치합니다.

cgroup v1은 저하된 모드로 실행됩니다

cgroup v1 호스트에서는 CPU/메모리 할당량이 적용되지 않습니다 (워크스페이스는 시작되지만 --cpus/--memory 제한 없이 실행됩니다). GPU 할당은 어느 경우에나 적용되며, 디스크는 측정되지만 차단되지는 않습니다. cgroup v2를 강력히 권장합니다.

첫 번째 부팅

설치 스크립트가 데이터베이스 초기화, root 관리자 비밀번호 설정, 서비스 시작까지 이미 자동으로 처리하므로 직접 실행할 필요가 없습니다. 실제 설치 과정(--check가 아닌 경우)에서는 터미널로 root LabPod 관리자 비밀번호를 물어보고(또는 --admin-password-file <path>로 비대화식으로 읽고), 스키마 마이그레이션을 실행한 다음, 비밀번호를 기록한 뒤 systemctl enable --now labpod를 실행합니다.

이 단계 중 하나를 수동으로 다시 실행해야 한다면, 예를 들어 --skip-app 이후이거나 막힌 설치를 복구할 때는 --db를 admin 뒤에 배치하세요:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

# 데이터베이스 스키마 적용
sudo labpod admin --db /var/lib/labpod/labpod.db migrate

# root LabPod 관리자 비밀번호 설정(또는 재설정)
sudo labpod admin --db /var/lib/labpod/labpod.db set-password root

# 서비스 활성화 및 시작
sudo systemctl enable --now labpod

# Run these as root
# 데이터베이스 스키마 적용
labpod admin --db /var/lib/labpod/labpod.db migrate

# root LabPod 관리자 비밀번호 설정(또는 재설정)
labpod admin --db /var/lib/labpod/labpod.db set-password root

# 서비스 활성화 및 시작
systemctl enable --now labpod

JWT 시크릿

프로덕션 환경에서는 /etc/labpod/labpod.env에 LABPOD_JWT_SECRET (32바이트 이상)이 필요합니다. 이 값이 없으면 서버가 시작을 거부합니다. 설치 프로그램이 강력한 시크릿을 자동으로 생성해 환경 파일에 기록하므로, 직접 설정할 필요는 없습니다. 나중에 이 값을 교체하면 모든 사용자가 로그아웃됩니다. 자세한 내용은 시크릿 교체를 참조하세요.

확인

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

systemctl status labpod
curl -s http://127.0.0.1:24680/api/health
curl -s http://127.0.0.1:24680/api/version      # 실행 중인 바이너리의 짧은 git SHA
sudo labpod admin doctor                         # 호스트 사전 요구사항, GPU 공유 런타임, GPU 인스펙터 확인 등

# Run these as root
systemctl status labpod
curl -s http://127.0.0.1:24680/api/health
curl -s http://127.0.0.1:24680/api/version      # 실행 중인 바이너리의 짧은 git SHA
labpod admin doctor                         # 호스트 사전 요구사항, GPU 공유 런타임, GPU 인스펙터 확인 등

doctor는 무언가 이상해 보일 때 쓰는 도구로, 호스트 사전 요구사항을 확인하고 고쳐야 할 사항을 보고합니다. 전체 워크스테이션 사전 점검을 위해서는 설치 스크립트의 --check 모드를 사용하세요.

이제 브라우저에서 http://<host>:24680을 열고 root로 로그인할 수 있습니다. LabPod은 기본값으로 인접한 24681 포트를 워크스페이스 앱 게이트웨이로도 사용합니다. LAN 방화벽이나 VPN에서 두 포트를 모두 허용해야 합니다. 연구자는 플랫폼 URL만 열면 되고, 워크스페이스 앱은 필요할 때 LabPod이 게이트웨이로 리디렉션합니다. 리버스 프록시를 구성하기 전에는 워크스페이스 게이트웨이를 확인하세요.

Trial

서명된 라이선스가 설치되어 있지 않으면 LabPod는 내장 90일 trial 권한으로 실행됩니다. trial 제한과 labpod admin license 명령어는 라이선스를 참고하세요.

다음 단계

• 사용자 및 할당량: 연구자 계정 생성 및 사용자별 제한 설정.
• GPU 구성: 분할 GPU 공유 또는 MIG 활성화.
• 템플릿 및 공유 마운트: 이미지 등록 및 공유 데이터셋 마운트.
• 백업 및 복구: 일별 타이머 및 복구 방법.
• 보안 및 강화: TLS, 포트 가드, 신뢰 경계.
• 워크스페이스 게이트웨이: 두 브라우저 origin과 방화벽 또는 리버스 프록시 요구사항.