참고 자료
오프라인 교재와 PC 열람
PC에서는 교재를 읽고, 실습 명령과 AI 코딩 도구는 준비된 VSCode Server의 참가자 작업 공간에서 사용합니다. 교재를 옮기기 위해 AWS 키나 CLI 로그인 파일을 PC에 복사할 필요가 없습니다. 14–18장의 GPU 운영 명령은 해당 장이 지정한 진행자·운영자 터미널에서만 실행합니다.
1. 내려받을 교재
진행자가 생성한 workshop/site/ 전체 또는 다음 두 파일을 받습니다.
workshop/.local/downloads/robot-atlas-workshop-handbook.zip
workshop/.local/downloads/robot-atlas-workshop-handbook.zip.sha256
VSCode Server 파일 탐색기나 진행자가 안내한 전송 방법으로 내려받습니다. 공개 교재 게시가 별도로 완료된 환경에서는 /workshop/의 교재 ZIP 버튼을 사용할 수 있습니다. 그 환경의 파일 경로는 다음과 같습니다.
/workshop/downloads/robot-atlas-workshop-handbook.zip
/workshop/downloads/robot-atlas-workshop-handbook.zip.sha256
전달받은 판본의 첫 페이지에서 Physical AI 로봇 워크숍 제목·갱신일·목차를 확인합니다. 교재는 다음 세 트랙의 00–18장을 포함합니다.
| 트랙 | 장 | 예상 합계 |
|---|---|---|
| 참가자 기본 | 00–04 | 약 110분 |
| 참가자 AWS 배포 | 05–13 | 약 280분 |
| 진행자·운영자 Isaac Sim·EKS | 14–18 | 약 195분 |
장별 시간과 트랙별 합계는 준비 상태·배포 대기·실습·질문에 맞춰 조정하는 예상치입니다. 전체 완료 시한이나 수업 일수를 정하는 값은 아닙니다.
14–18장은 이미 배포된 전용 gpu-cluster-01의 Isaac Sim·EKS 경로를 다룹니다. 진행자·운영자만 현재 계정·기존 VPC의 Private g6e/g7e GPU 환경을 운영합니다. 교재 열람과 실제 GPU·물리 실행 성공은 구분하며, 통제된 체크포인트 복구를 실제 EC2 Spot 회수 알림 주입으로 기록하지 않습니다.
2. 체크섬 확인과 압축 해제
ZIP과 .zip.sha256을 같은 폴더에 둡니다. Linux에서는 다운로드 폴더에서 다음을 실행하면 파일 내용이 체크섬과 같은지 확인할 수 있습니다.
sha256sum -c robot-atlas-workshop-handbook.zip.sha256
macOS에서는 다음을 사용합니다.
shasum -a 256 -c robot-atlas-workshop-handbook.zip.sha256
기대 결과는 robot-atlas-workshop-handbook.zip: OK입니다. 불일치하면 같은 판본의 ZIP·체크섬을 다시 받습니다. 체크섬 일치는 파일 전송의 무결성 확인이며 AWS 배포나 실습 실행 성공을 증명하지 않습니다.
ZIP 전체를 압축 해제한 뒤 다음 파일을 브라우저로 엽니다. ZIP 안에서 HTML 하나만 미리 보기로 열지 않습니다.
robot-atlas-workshop/
├── START-HERE.txt
├── index.html
├── chapters/
├── reference/
├── prompts/
├── assets/
├── manifest.webmanifest
└── sw.js
진입 파일은 robot-atlas-workshop/index.html입니다. chapters, reference, prompts, assets를 함께 유지합니다. workshop/site/를 직접 복사했다면 그 폴더의 index.html을 엽니다.
3. file://로 읽기
압축을 푼 교재는 본문과 글꼴·스타일·스크립트를 로컬 파일에서 읽습니다. 교재 열람에 Node, Python, Docker 또는 웹 서버를 실행할 필요가 없습니다. 목차·장 이동·테마·프롬프트를 확인하고, 복사 버튼이 브라우저에서 제한되면 텍스트를 선택해 복사합니다.
file://에서는 서비스 워커를 등록하지 않습니다. ZIP 안의 sw.js를 별도로 실행하거나 PWA를 설치해야 읽을 수 있는 구조가 아닙니다. 파일 위치나 브라우저가 달라지면 읽음 상태가 유지되지 않을 수 있으며, 저장소를 막는 브라우저 설정에서도 본문은 계속 읽을 수 있습니다.
AI 프롬프트는 선택한 Codex·Kiro CLI·Claude Code의 대화창으로, 터미널 명령은 해당 장이 지정한 참가자 터미널로 옮깁니다. PC의 다운로드 폴더에서 AWS 배포 명령을 실행하지 않습니다.
4. ZIP에 들어 있는 것과 별도로 필요한 것
| 구분 | 내용 |
|---|---|
| 포함 | 공개 HTML 교재, 교재용 CSS·JavaScript·폰트·아이콘, 프롬프트 카드, 문서 안의 명령·코드 예제 |
| 포함하지 않음 | 전체 Robot Atlas 앱 소스, 실행 가능한 런타임/컨테이너, Node·Python 설치 파일과 의존성 |
| 포함하지 않음 | MuJoCo 엔진·로봇 모델 파일, NVIDIA Isaac Sim 이미지·USD/장면 자산, 학습 모델 가중치 |
| 포함하지 않음 | 참가자 작업 공간·설정, .env, AWS 자격 증명, API 키, 로그인 파일, 배포 상태, 개인 실행 기록 |
ZIP은 공개 교재이며 전체 실습 실행 묶음이 아닙니다. 문서에 코드 예제가 있어도 앱 저장소나 의존성이 설치된 것은 아닙니다. 필요한 소스와 실행 환경은 진행자가 별도로 준비합니다.
5. 오프라인에서 가능한 범위
| 작업 | 필요한 준비와 연결 |
|---|---|
| ZIP의 교재 읽기 | 압축 해제한 전체 교재와 브라우저. 네트워크 불필요 |
| 코드·프롬프트 복사 | 교재 열람 가능. AI 도구의 실제 응답은 별도 연결/인증 필요 |
| 로컬 MuJoCo 물리 실행 | 저장소·모델 파일·Python/MuJoCo 의존성이 이미 설치되어 있어야 함 |
| 로컬 웹·규칙 계획 | Node 의존성·빌드 자산·로컬 API/시뮬레이터가 미리 준비되어 있어야 함 |
| Bedrock 실제 계획 | AWS 네트워크, 참가자 자격 증명과 모델 권한 필요 |
| AWS 배포·검증·정리 | 네트워크와 참가자 계정 권한 필요 |
| Isaac Sim·EKS GPU 과정 | 진행자·운영자의 전용 EKS·Private GPU·런타임·자산과 네트워크 필요 |
처음 하는 npm ci, Python 패키지 설치, 컨테이너·자산 다운로드는 준비된 캐시나 네트워크가 필요합니다. 오프라인 준비 여부는 진행자가 실제 로컬 실행으로 확인합니다. 교재 ZIP만 받은 상태에서 물리 엔진이나 모델이 실행된다고 설명하지 않습니다.
실습이 원격 EC2에 있다면 PC와 VSCode Server 사이 연결도 필요합니다. EC2에 설치가 끝났다는 사실이 PC에서 네트워크 없이 원격 터미널을 쓸 수 있다는 뜻은 아닙니다.
6. HTTPS 교재의 PWA 오프라인 읽기
공개 게시된 HTTPS 교재에서는 ZIP과 별도로 PWA 오프라인 저장을 사용할 수 있습니다.
- 연결된 상태에서
/workshop/교재를 엽니다. - “전체 교재를 오프라인으로 읽을 수 있습니다.”라는 저장 완료 안내를 확인합니다.
- 지원하는 브라우저에서 설치 버튼이나 메뉴의 앱 설치·홈 화면 추가를 사용합니다.
- 연결을 끊고 아직 열지 않았던 다른 장을 열어 교재 저장을 확인합니다.
- 새 판본 안내가 나오면 원하는 시점에 “업데이트 적용” 또는 “새 버전 열기”를 선택합니다.
워크숍의 저장 범위는 해당 교재 경로입니다. 로봇 API, 개인 실행 기록, 모델 서비스, 다운로드 ZIP을 오프라인 캐시로 제공하는 기능은 아닙니다. ZIP 자체도 보관하려면 연결되어 있을 때 별도로 내려받습니다.
브라우저가 저장 공간을 지우거나 저장에 실패하면 다시 연결해 저장 상태를 확인합니다. PWA 설치·읽음 표시는 학습 편의 상태이며 실제 배포나 모델·물리 실습 성공의 근거가 아닙니다.
7. 교재 다시 만들기
진행자나 교재 편집자는 원본 저장소 루트의 준비된 Node 24·Python 3.11 환경에서 실행합니다. 참가자 앱에 복사한 배포 스크립트와 구분합니다.
cd /home/ec2-user/my-project/robot-arm
npm run workshop:build
npm run workshop:package
workshop:build는 workshop/site/를 생성합니다. workshop:package는 교재를 다시 빌드한 뒤 workshop/.local/downloads/에 ZIP·SHA-256을 만듭니다. Python 실행 경로를 선택해야 한다면 다음처럼 지정합니다.
ROBOT_PYTHON="$(command -v python3)" npm run workshop:package
직접 실행할 때의 같은 절차입니다.
node workshop/scripts/build.mjs
python3 workshop/scripts/package_handbook.py \
--site workshop/site \
--output workshop/.local/downloads/robot-atlas-workshop-handbook.zip
패키저는 표시된 생성 marker와 파일 목록·체크섬을 검사합니다. 누락 문서, 수정된 생성물, 개인 파일이나 symlink가 있으면 거부합니다. site/에 자료를 임의로 추가하거나 marker를 편집하지 말고 소스를 고쳐 다시 빌드합니다.
npm run workshop:public은 게시용 dist/workshop/와 그 안의 downloads/를 만듭니다. 이 역시 로컬 조립이며 AWS 게시를 수행하지 않습니다. 다운로드를 포함한 dist/workshop/는 깨끗한 패키징 입력을 대신할 수 없습니다.
문제 해결과 완료 확인
| 증상 | 확인 |
|---|---|
| 글꼴·스타일·목차가 없음 | HTML만 열었는지, ZIP 전체를 풀고 폴더 구조를 유지했는지 |
| 체크섬 불일치 | ZIP과 체크섬이 같은 판본인지, 전송이 완료됐는지 |
| 프롬프트 복사 실패 | 브라우저 제한. 본문을 선택해 복사 |
| 오프라인 PWA에서 문서가 안 열림 | 전체 저장 완료 여부와 브라우저 저장 공간 삭제 여부 |
file://에서 설치 버튼이 없음 |
정상. 로컬 파일 열람은 서비스 워커나 PWA 설치가 필요하지 않음 |
| 로컬 로봇이 실행되지 않음 | 교재와 실행 환경을 구분하고 사전 설치된 저장소·의존성 확인 |
| 모델·AWS 요청 실패 | 네트워크·계정·권한 확인. 교재가 열리는 것과 별개 |
- 전체 폴더의
index.html과 다른 장이 열립니다. - 글꼴·스타일·목차와 프롬프트를 확인했습니다.
- 받은 ZIP의 무결성과 판본을 확인했습니다.
- 교재 ZIP과 실제 실행 환경·AWS 연결을 구분했습니다.
- 읽음 상태를 실습 성공으로 기록하지 않았습니다.
다음으로 00. 이번 실습에서 만들 것을 읽거나, 환경 준비와 문제 해결을 확인합니다.