설치 및 첫 번째 부팅

이 문서는 운영자가 베어 Linux GPU 워크스테이션에 LabPod를 설치해 root 관리자 계정으로 서버를 실행하기까지의 과정을 안내합니다. 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를 실행할 수 있습니다.

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

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

첫 번째 부팅

설치 스크립트가 데이터베이스 초기화, 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

설정 확인하기

설치된 /etc/labpod/labpod.env는 의도적으로 짧습니다. 데이터베이스 경로와 JWT 시크릿만 설정되어 있습니다. LabPod은 NVIDIA/MIG 지원 여부를 비롯한 나머지를 스스로 감지하므로, CPU 전용 호스트와 GPU 호스트가 같은 최소 파일로 부팅합니다. 이 호스트가 실제로 무엇을 쓰고 있는지 확인하려면 다음을 실행하세요.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod env       # 이 호스트의 명시적 재정의와 자동 감지 결과
sudo labpod env --all # 설정되지 않아 기본값을 쓰는 항목까지 포함한 모든 설정, 그리고 legacy 호환 키

# Run these as root
labpod env       # 이 호스트의 명시적 재정의와 자동 감지 결과
labpod env --all # 설정되지 않아 기본값을 쓰는 항목까지 포함한 모든 설정, 그리고 legacy 호환 키

전체 참조는 환경 변수를 확인하세요.

루트리스 Podman 저장소

연구자마다 루트리스 Podman을 실행하므로 이미지, 컨테이너 레이어, 볼륨 저장소도 계정별로 나뉩니다. Podman은 기본적으로 <passwd-home>/.local/share/containers/storage를 사용합니다. 이 경로는 LabPod 사용자 데이터 및 LABPOD_WORK_BASE와 별개입니다.

다른 로컬 디스크를 모든 루트리스 사용자의 기본 저장소로 지정하려면 /etc/containers/storage.conf의 기존 [storage] 테이블에 rootless_storage_path를 추가합니다.

[storage]
rootless_storage_path = "/data/labpod-podman/$USER/storage"

/etc/containers/storage.conf가 없으면 배포판이 제공한 전체 파일을 먼저 복사합니다. 일반적인 원본 경로는 /usr/share/containers/storage.conf입니다. 저장소 설정 파일은 우선순위가 낮은 파일과 병합되지 않고 그 파일을 완전히 대체하므로, 이 설정만 담은 불완전한 시스템 파일을 만들면 안 됩니다.

배포판이 제공한 파일의 나머지 내용은 그대로 유지합니다. Podman 저장소 라이브러리가 $USER를 각 계정명으로 바꾸므로 사용자마다 격리된 저장소를 사용합니다. 여러 사용자가 하나의 쓰기 가능 graphroot를 함께 사용하도록 설정하면 안 됩니다. LabPod의 root 관리 공유 이미지 저장소는 별도의 다운로드 캐시이며 워크스페이스가 그 저장소에서 직접 실행되지는 않습니다.

일반적인 ext4 또는 XFS 데이터 디스크처럼 OverlayFS 메타데이터와 확장 속성을 지원하는 로컬 파일시스템을 사용합니다. 루트리스 Podman 저장소는 NFS, Lustre, GPFS 같은 분산 홈 파일시스템을 지원하지 않습니다. 자세한 내용은 Podman의 루트리스 저장소 문서와 containers-storage.conf 참조를 확인하세요.

사용자가 이미지를 처음 풀하기 전에 LabPod 사용자별 상위 디렉터리를 만들고 해당 계정에 소유권을 부여합니다.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo install -d -m 0711 /data/labpod-podman

user=alice
group=$(id -gn "$user")
sudo install -d -m 0700 -o "$user" -g "$group" "/data/labpod-podman/$user"

# Run these as root
install -d -m 0711 /data/labpod-podman

user=alice
group=$(id -gn "$user")
install -d -m 0700 -o "$user" -g "$group" "/data/labpod-podman/$user"

SELinux 호스트에서는 새 트리에 컨테이너 저장소 레이블을 지정한 뒤 적용합니다.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo semanage fcontext -a -t container_var_lib_t '/data/labpod-podman(/.*)?'
sudo restorecon -RFv /data/labpod-podman

# Run these as root
semanage fcontext -a -t container_var_lib_t '/data/labpod-podman(/.*)?'
restorecon -RFv /data/labpod-podman

<passwd-home>/.config/containers/storage.conf에 계정별 설정 파일이 있으면 시스템 저장소 설정을 상속하지 않고 그 파일이 우선합니다. 기존 Linux 계정을 인수한 경우에는 이 파일이 이미 있을 수 있습니다. 기존 driver와 option은 유지하고, 새 배치를 따르게 할 계정은 해당 파일의 [storage] graphroot를 사용자별 대상 경로로 설정합니다.

기존 저장소 옮기기

rootless_storage_path를 바꾸면 Podman이 탐색할 경로만 달라지며 기존 이미지와 컨테이너는 자동으로 옮겨지지 않습니다. 연구자가 이미지를 풀하기 전에 설정하는 방법이 가장 간단하고 안전합니다. Podman을 이미 사용한 계정은 다음 순서로 옮깁니다.

해당 계정의 모든 LabPod 워크스페이스와 그 밖의 루트리스 컨테이너를 중지합니다.
현재 graphroot를 기록합니다.
이전 중 모니터링이나 라이프사이클 호출이 실행되지 않도록 labpod.service를 중지한 뒤 podman system migrate로 Podman pause 프로세스를 중지합니다.
하드 링크, 확장 속성, ACL, 서브 ID의 숫자 소유권을 유지하면서 graphroot 전체를 복사합니다.
시스템 경로 템플릿 또는 위에서 설명한 계정별 graphroot를 변경합니다.
SELinux 레이블을 적용하고 유효 경로와 이미지 목록을 확인한 뒤 LabPod을 다시 시작합니다.

시스템 전체 설정을 바꾸기 전에 기존 계정마다 다음 복사를 반복합니다.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

user=alice
home=$(getent passwd "$user" | cut -d: -f6)
uid=$(id -u "$user")
group=$(id -gn "$user")
runtime="/run/user/$uid"

old=$(sudo -u "$user" env HOME="$home" XDG_RUNTIME_DIR="$runtime" \
  podman info --format '{{.Store.GraphRoot}}')
new="/data/labpod-podman/$user/storage"

sudo systemctl stop labpod
sudo -u "$user" env HOME="$home" XDG_RUNTIME_DIR="$runtime" podman system migrate
sudo install -d -m 0711 /data/labpod-podman
sudo install -d -m 0700 -o "$user" -g "$group" "$new"
sudo rsync -aHAX --numeric-ids "$old/" "$new/"

# Run these as root
user=alice
home=$(getent passwd "$user" | cut -d: -f6)
uid=$(id -u "$user")
group=$(id -gn "$user")
runtime="/run/user/$uid"

old=$(sudo -u "$user" env HOME="$home" XDG_RUNTIME_DIR="$runtime" \
  podman info --format '{{.Store.GraphRoot}}')
new="/data/labpod-podman/$user/storage"

systemctl stop labpod
runuser -u "$user" -- env HOME="$home" XDG_RUNTIME_DIR="$runtime" podman system migrate
install -d -m 0711 /data/labpod-podman
install -d -m 0700 -o "$user" -g "$group" "$new"
rsync -aHAX --numeric-ids "$old/" "$new/"

rootless_storage_path와 SELinux를 설정한 뒤 같은 Linux 계정으로 결과를 확인합니다.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo -u "$user" env HOME="$home" XDG_RUNTIME_DIR="$runtime" \
  podman info --format '{{.Store.GraphRoot}}'
sudo -u "$user" env HOME="$home" XDG_RUNTIME_DIR="$runtime" podman images
sudo -u "$user" env HOME="$home" XDG_RUNTIME_DIR="$runtime" podman ps -a
sudo systemctl start labpod
sudo labpod admin doctor

# Run these as root
runuser -u "$user" -- env HOME="$home" XDG_RUNTIME_DIR="$runtime" \
  podman info --format '{{.Store.GraphRoot}}'
runuser -u "$user" -- env HOME="$home" XDG_RUNTIME_DIR="$runtime" podman images
runuser -u "$user" -- env HOME="$home" XDG_RUNTIME_DIR="$runtime" podman ps -a
systemctl start labpod
labpod admin doctor

이미지와 컨테이너 목록이 일치하고 워크스페이스가 정상적으로 시작되는지 확인할 때까지 기존 저장소를 보관합니다. 개별 레이어 디렉터리를 직접 삭제하면 안 됩니다.

확인

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이 게이트웨이로 리디렉션합니다. 리버스 프록시를 구성하기 전에는 워크스페이스 게이트웨이를 확인하세요.

다음 단계

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