업그레이드

릴리스 채널에서 업그레이드

이미 LabPod가 설치된 호스트에서 공개 설치 스크립트를 다시 실행하세요:

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.4.0

# 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.4.0

기존 설치에서 설치 프로그램은 다음 작업을 수행합니다:

1. 릴리스 다운로드: 릴리스 tarball을 다운로드하고 체크섬과 서명을 검증합니다.
2. 업그레이드 전 복구 세트: 다운로드한 바이너리가 설치된 바이너리와 다르면 실행 파일, 애플리케이션 지원 파일, 데이터베이스 스냅샷을 교체 작업 전에 /var/lib/labpod/backups/pre-upgrade-<UTC>.*로 보관합니다. 데이터베이스 스냅샷을 의도적으로 생략할 때만 --skip-backup을 전달합니다.
3. 후보 버전 고정 및 파일 갱신: latest를 변경되지 않는 릴리스 태그로 확정하고 후보 바이너리가 그 버전을 보고하는지 검증합니다. 릴리스 내용이 변경된 경우에만 /usr/local/bin/labpod와 /opt/labpod/inject 트리를 교체합니다.
4. 설정 보존: /etc/labpod/labpod.env, /var/lib/labpod/labpod.db, 백업, 라이선스, TLS 캐시, Linux 계정, 사용자 홈 디렉터리를 보존합니다.
5. Unit 갱신: 최신 systemd unit 파일을 /etc/systemd/system/에 복사합니다.
6. 사전 점검, 마이그레이션, 재시작: API를 중지하기 전에 데이터베이스, 이미지 저장소, TLS, GPU 공유, inject 트리 경로를 검증합니다. 설정 오류가 있으면 실행 중인 서비스를 그대로 유지하므로 수정한 뒤 설치 프로그램을 다시 실행할 수 있습니다. 유효한 업그레이드에서는 파일을 갱신하고 영속적인 데이터베이스 업그레이드를 적용하는 동안 LabPod API만 중지합니다.
7. 재시작 후 상태 확인 및 롤백: /api/version을 폴링하고 재시작한 API가 확정된 릴리스를 보고하는지 검증합니다. 업그레이드 단계가 실패하면 이전 실행 파일, 지원 파일, 마이그레이션을 시작한 경우의 데이터베이스, API 서비스, 백업 타이머를 자동으로 복원합니다. 이전 API가 정상인지 다시 확인한 뒤 롤백 성공을 보고합니다. 자동 롤백까지 실패한 경우에만 수동 복구가 필요합니다.

실제 업그레이드에서는 복구 세트가 자동으로 생성됩니다. 설치된 바이너리와 동일한 바이너리로 다시 실행하는 경우에는 생성하지 않습니다. 설치 프로그램은 기본적으로 최신 복구 세트 10개를 유지하며, 오래된 실행 파일, 애플리케이션 파일 스냅샷, 짝을 이루는 데이터베이스 스냅샷을 함께 정리합니다. 일별 labpod-*.db 백업에는 별도의 보존 정책이 적용됩니다.

사용자 지정 백업 디렉터리는 updater와 지원 파일 디렉터리 및 별도 위치의 inject 트리 밖에 두세요. 롤백이 복원에 사용하는 파일을 삭제하거나 자기 자신에게 재귀 복사해서는 안 됩니다. --skip-backup을 전달한 뒤 마이그레이션이 시작되면 자동 롤백에 복원할 데이터베이스 스냅샷이 없습니다.

더 신중하게 진행하려면 업그레이드 전에 수동 백업을 추가로 생성할 수 있습니다:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin backup --out /var/lib/labpod/backups/pre-upgrade-$(date -u +%Y%m%dT%H%M%SZ).db

# Run these as root
labpod admin backup --out /var/lib/labpod/backups/pre-upgrade-$(date -u +%Y%m%dT%H%M%SZ).db

실행 중인 워크스페이스 유지

워크스페이스 컨테이너는 재시작 중에도 계속 실행됩니다. LabPod 서비스 재시작은 약 2초 걸립니다. 그 순간 처리 중이던 API 요청은 실패할 수 있지만 컨테이너 자체(Jupyter 커널과 학습 실행)는 계속됩니다. 워크스페이스 페이지와 앱은 서비스가 돌아온 뒤 다시 로드됩니다. LabPod Terminal은 자동으로 다시 연결하며 tmux 세션과 스크롤백을 유지합니다.

새 API 호출은 재시작 후 약 2초 내에 새 바이너리에서 처리됩니다.

업그레이드 후 워크스페이스 템플릿 이미지

이제 모든 기본 제공 워크스페이스 템플릿은 움직이는 태그 대신 고정된 이미지 버전을 씁니다. 이 핀이 바뀌는 업그레이드에서는 사용 중인 워크스페이스 템플릿마다 이미지를 한 번씩 새로 받아야 한다고 예상하세요. 예를 들어 PyTorch, TensorFlow, SciPy, Code Server, PyTorch Demo는 :cu126, :py312, :latest 같은 태그에서 v1-... 버전으로 바뀝니다. 이름만 바뀐 것이 아니라 실제로 다른 이미지이므로 이 호스트에 이미 받아 둔 이미지로는 새 핀을 만족하지 못합니다.

실행 중인 워크스페이스는 영향을 받지 않습니다. 이미 실행 중인 컨테이너를 그대로 씁니다. 이미지가 바뀐 중지된 워크스페이스를 시작하면 이미지를 먼저 다운로드해야 한다는 안내가 나옵니다. 연구자가 관리자 빌드 없이 워크스페이스 페이지에서 직접 다운로드할 수 있습니다. 각 연구자는 별도의 루트리스 이미지 저장소를 사용하므로 각 계정은 해당 워크스페이스 템플릿을 처음 쓸 때 새 핀을 다운로드합니다. 네트워크 레지스트리 캐시를 사용하면 반복되는 네트워크 전송을 줄일 수 있습니다.

업그레이드는 비활성화해 둔 워크스페이스 템플릿을 절대 켜지 않습니다. 활성화/비활성화 선택은 그대로 유지됩니다. 이제 게시된 이미지로 바뀐 워크스페이스 템플릿(Miniforge, uv, R ML, RStudio, Hugging Face, ComfyUI, CUDA Composite, Parallel Programming) 중 하나를 이미 활성화하고 로컬로 빌드해 두었다면, 이제부터는 로컬 빌드 대신 검증된 게시 이미지를 가리킵니다. 이전에 빌드해 둔 이미지는 각 사용자 저장소에 그대로 남아 있으므로 더 이상 필요 없으면 해당 사용자가 Advanced tools → Workspace templates → My images에서 제거합니다. 계속 직접 빌드한 이미지를 쓰려면 해당 워크스페이스 템플릿의 이미지 참조를 편집하세요. 그러면 사용자 정의로 표시되어 LabPod이 더 이상 출고 기본값을 다시 적용하지 않습니다.

업그레이드는 지원이 종료된 LABPOD_SHARED_IMAGE_STORE_MODE와 LABPOD_SHARED_IMAGE_STORE 설정을 제거하고 대기 중인 이미지 승격 요청을 삭제합니다. 이전 root 캐시 디렉터리의 파일은 삭제하지 않으므로 더 이상 필요하지 않은지 확인한 뒤 직접 제거합니다.

마이그레이션 정책

LabPod 스키마 마이그레이션은 순방향 전용입니다. 업그레이드된 데이터베이스는 해당 마이그레이션을 수행한 릴리스 또는 그보다 새 릴리스와 함께 실행해야 합니다. 이전 DB를 복원한 상태에서 업그레이드된 새 바이너리를 실행하지 말고 이미 마이그레이션된 DB를 이전 바이너리로 실행하지 마세요.

설치 프로그램은 짝을 이루는 pre-upgrade-* 복구 세트로 자동 롤백합니다. 설치된 DB나 내부 스키마 상태를 직접 수정하지 마세요.

업그레이드가 실패하는 경우

자동 롤백이 성공해도 설치 프로그램은 0이 아닌 상태로 종료하여 업데이트 실패를 분명히 표시합니다. /api/version이 이전 버전을 보고하는지 확인하고 설치 프로그램 출력과 journalctl -u labpod를 검토하세요. 원인을 해결한 뒤 다시 시도합니다.

자동 롤백을 완료하지 못하면 설치 프로그램이 서비스가 중지된 상태에서 복구할 정확한 명령과 해당 시도의 실행 파일, 애플리케이션 파일, 데이터베이스 스냅샷 이름을 출력합니다. 호스트 셸에서 그 명령을 따르세요. 짝을 이루는 스냅샷을 복원하기 전에 고정된 이전 bootstrap이나 이전 릴리스의 설치 프로그램을 시작하면 잘못된 데이터베이스 세대에 마이그레이션을 실행할 수 있습니다. 데이터베이스 스키마와 실행 파일은 같은 릴리스 세대여야 합니다.

보관된 릴리스로 되돌리기

설치 프로그램은 업그레이드 직전 상태를 복구 세트로 남깁니다. 업그레이드를 마친 뒤에 문제가 드러나면 root 관리자가 호스트 셸에서 그중 하나를 복원할 수 있습니다.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin rollback list
sudo labpod admin rollback apply 20260812T120000Z --yes

# Run these as root
labpod admin rollback list
labpod admin rollback apply 20260812T120000Z --yes

list는 복구 ID, 보관된 버전, 그리고 각 세트가 완전한지, 호환되는지, 적용할 수 있는지를 보여줍니다. 적용할 수 없는 세트는 그 이유도 함께 출력합니다. 인벤토리 도구에서 쓰려면 --json을 붙이세요. apply는 완전하면서 설치된 것보다 오래된 바이너리를 가진 세트만 받습니다. 먼저 현재 설치 상태를 새 복구 세트로 저장하고, API를 중지한 다음, 보관된 바이너리와 애플리케이션 파일과 짝이 되는 데이터베이스를 복원하고, API를 다시 시작해 /api/version을 확인합니다. 복원한 서버가 정상으로 돌아오지 않으면 직전에 저장한 세트를 되돌려 놓고 0이 아닌 상태로 종료합니다.

롤백은 해당 세트의 데이터베이스 스냅샷을 항상 함께 복원하므로 그 복구 시점 이후에 반영된 LabPod 변경 사항은 사라집니다. 워크스페이스 파일은 되돌아가지 않고 루트리스 워크스페이스 컨테이너도 계속 실행됩니다. --yes가 필요한 이유이자 웹 화면에 이 동작을 실행하는 버튼이 없는 이유입니다.

관리자 UI에서 업데이트

이 릴리스를 한 번 설치한 뒤에는 root 관리자가 Admin → Software update에서 공개 릴리스 채널을 확인하고 업그레이드를 시작할 수 있습니다. 이 페이지는 공개 설치 명령과 같은 서명 패키지와 체크섬 검증을 사용하고 설치 프로그램 로그를 기록하며 같은 업그레이드 전 데이터베이스 백업을 포함한 복구 세트를 만듭니다.

자동 확인은 기본으로 꺼져 있습니다. 호스트가 공개 릴리스 서비스에 연결해도 될 때만 켜세요. LabPod은 24시간마다 새 버전을 확인하지만 관리자의 동의 없이 설치하지 않습니다. 에어갭 호스트는 위의 설치 명령을 계속 사용하면 됩니다. 터미널에서는 labpod admin update status, check, apply로 같은 작업을 수행할 수 있습니다.

예약된 업데이트가 실행될 때

예약된 업데이트는 배너로 알립니다. Apply now를 누르면 예정 시각보다 먼저 시작하고, 업데이트가 실제로 시작되면 이 버튼은 사라집니다. 다시 눌러도 이미 진행 중이라는 안내밖에 나오지 않기 때문입니다. Cancel update는 설치 프로그램이 시작되기 전까지 쓸 수 있습니다.

서버가 다시 시작된 뒤에도 열어 둔 탭은 이전 버전의 인터페이스를 그대로 띄우고 있어, 새 버전에는 없는 자원을 서버에 요청할 수 있습니다. Software update 페이지의 Reload the interface가 이때 쓰는 버튼이고, 탭과 설치된 서버가 같아지면 안내는 더 나오지 않습니다. 같은 이유로 페이지가 열리지 않을 때도 밋밋한 “Internal Error” 대신 원인을 설명하고 Reload를 제안합니다.

Linux 계정 HOME 옮기기

LabPod은 호스트 계정 데이터베이스에 기록된 HOME을 따르며 별도의 계정 홈 기준 경로를 두지 않습니다. 설치 후 계정 HOME을 옮기려면 해당 계정의 워크스페이스와 LabPod 서비스를 중지한 뒤, workspaces와 이전하지 않은 work를 포함한 전체 HOME을 옮깁니다. 소유권을 유지하고 LabPod을 다시 시작하기 전에 passwd HOME을 새 경로로 변경합니다.

기존 워크스페이스는 이전 경로가 사라질 때까지 기록된 영속 홈을 계속 사용합니다. 이 전환 기간에는 Files 보기도 기존 경로를 따르고 데이터가 고아가 되지 않도록 LabPod이 workspace_home_migration_required 오류로 Delete를 거부합니다. LabPod은 이 이동을 대신하지 않으므로 기존 디렉터리를 지우기 전에 복사를 확인하세요.

루트리스 Podman 저장소는 계정 데이터와 별개입니다. 아직 기존 HOME 아래에 있다면 따로 이전해야 합니다. 자세한 절차는 루트리스 Podman 저장소를 참조하세요.