환경과 참가자 작업 공간

이 장의 예상 시간은 약 10분입니다. 도구 확인, 참가자 설정, 사본 준비와 빌드를 진행하며 준비 상태와 질문에 맞춰 시간을 조정합니다. 진행자는 패키지 다운로드와 AI CLI 인증을 수업 전에 확인합니다. VPC, EC2, 편집기를 새로 설치하는 시간은 포함하지 않습니다.

1. 준비된 도구 확인

cd /home/ec2-user/my-project/robot-arm
export ROBOT_REPO="$PWD"
node --version
python3 --version
uv --version
npm --version
python3 - <<'PY'
import sys
assert sys.version_info[:2] == (3, 11), "진행자가 준비한 Python 3.11 경로를 사용하세요."
print("Python 3.11 확인")
PY

Node는 24.18.1 이상인 24 계열, Python은 3.11이어야 합니다. 버전이 다르면 진행자가 제공한 경로를 사용합니다. 공유 호스트의 기본 Python이나 전역 CLI를 참가자가 교체하지 않습니다.

설치된 AI 코딩 도구 중 하나만 고릅니다. 사용법과 작업 경계는 AI CLI 안내에 있습니다. 핵심 과정에서는 AgentCore CLI와 Docker를 사용하지 않습니다.

2. 참가자 설정 만들기

team01은 예시입니다. 진행자가 배정한 3–10자의 영문 소문자·숫자 조합으로 바꿉니다. 계정 ID는 진행자가 배정한 12자리 값을 입력합니다. 이는 이후 AWS 대상의 경계이며, 입력만으로 자격 증명이 검증되지는 않습니다.

export ROBOT_TEAM=team01
export ROBOT_CONFIG="$ROBOT_REPO/workshop/.local/$ROBOT_TEAM.json"
read -r -p "배정된 AWS 계정 ID 12자리: " ROBOT_ACCOUNT_ID
export ROBOT_PROFILE=""

python3 "$ROBOT_REPO/workshop/scripts/lab.py" init \
  --participant "$ROBOT_TEAM" \
  --account-id "$ROBOT_ACCOUNT_ID" \
  --profile "$ROBOT_PROFILE" \
  --config "$ROBOT_CONFIG"

python3 "$ROBOT_REPO/workshop/scripts/lab.py" doctor --config "$ROBOT_CONFIG"

EC2 역할을 사용할 때 ROBOT_PROFILE은 빈 값입니다. 진행자가 별도 프로필을 배정했다면 init 전에 그 이름을 지정합니다. 이름은 자격 증명이 아니며, 키나 토큰을 설정 JSON에 넣지 않습니다. doctor의 필수 항목과 전체 ok가 true인지 확인합니다. 선택 도구인 Docker 등의 ok: false는 로컬 핵심 과정의 실패가 아닙니다. AWS 접근 확인은 04장에서 doctor --aws로 수행합니다.

설정이 이미 있다면 init을 다시 실행하거나 덮어쓰지 않습니다. 본인 설정인지 확인한 뒤 다음의 info를 사용합니다.

3. 격리된 소스 사본 준비

python3 "$ROBOT_REPO/workshop/scripts/lab.py" prepare --config "$ROBOT_CONFIG"
python3 "$ROBOT_REPO/workshop/scripts/lab.py" info --config "$ROBOT_CONFIG"

다음 값을 확인합니다.

prepare는 허용된 코드·공개 모델·폰트와 라이선스를 사본에 준비합니다. 운영 .env, 자격 증명, 배포 상태, 실제 실행 기록을 복사하지 않습니다. 참가자용 로컬 설정과 세션은 참가자 폴더에서 별도로 생성합니다. 기존 사본을 다시 준비하면 덮어쓰기 오류가 나므로, 작업을 이어갈 때는 info만 실행합니다.

4. 터미널마다 작업 경로와 포트 불러오기

아래 블록은 이후 새로 여는 EC2 터미널마다 실행합니다. team01을 본인 이름으로 바꾸면 나머지 경로와 포트는 info에서 읽습니다. info 출력 전체를 쉘 코드로 실행하는 eval은 사용하지 않습니다.

export ROBOT_REPO=/home/ec2-user/my-project/robot-arm
export ROBOT_TEAM=team01
export ROBOT_CONFIG="$ROBOT_REPO/workshop/.local/$ROBOT_TEAM.json"
ROBOT_INFO="$(python3 "$ROBOT_REPO/workshop/scripts/lab.py" info --config "$ROBOT_CONFIG")"
export ROBOT_LAB="$(printf '%s' "$ROBOT_INFO" | python3 -c 'import json,sys; print(json.load(sys.stdin)["workspace"])')"
export ROBOT_API_PORT="$(printf '%s' "$ROBOT_INFO" | python3 -c 'import json,sys; print(json.load(sys.stdin)["ports"]["api"])')"
export ROBOT_SIM_PORT="$(printf '%s' "$ROBOT_INFO" | python3 -c 'import json,sys; print(json.load(sys.stdin)["ports"]["simulation"])')"
export ROBOT_API_URL="$(printf '%s' "$ROBOT_INFO" | python3 -c 'import json,sys; print(json.load(sys.stdin)["urls"]["api"])')"
export ROBOT_BROWSER_ORIGIN="$ROBOT_API_URL"
cd "$ROBOT_LAB"
printf '작업 폴더: %s\nAPI: %s\n시뮬레이터 포트: %s\n' "$PWD" "$ROBOT_API_URL" "$ROBOT_SIM_PORT"
test "$PWD" = "$ROBOT_REPO/workshop/.local/labs/$ROBOT_TEAM/app"

도구를 실행하기 전 마지막 경로 검사가 성공해야 합니다. 고정 포트 8098·8099나 운영 폴더에서 서버를 시작하지 않습니다.

5. 의존성과 빌드 준비

참가자 폴더에서 실행합니다. 진행자가 이미 준비한 .venv가 있으면 그대로 사용합니다.

cd "$ROBOT_LAB"
npm ci
test -x .venv/bin/python || uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -r simulation/requirements.txt
.venv/bin/python -c 'import mujoco; print("MuJoCo", mujoco.__version__)'
npm run build
test -f dist/index.html
test -f build/server/main.js
mkdir -p .local/evidence

MuJoCo 버전은 고정 의존성의 3.3.7이며, 빌드 후 두 파일 검사가 성공해야 합니다. 핵심 물리 계산은 CPU에서 수행합니다. 여기서 Isaac Sim이나 GPU 드라이버를 설치하지 않습니다. 패키지 설치가 끝나지 않았다면 성공으로 넘기지 말고 진행자가 준비한 캐시·환경을 확인합니다.

브라우저가 EC2에 접속하는 방법

EC2 터미널에서의 127.0.0.1과 참가자 PC 브라우저의 127.0.0.1은 서로 다른 컴퓨터입니다. 진행자가 제공한 포트 전달로 본인 API 포트를 PC의 같은 포트에 연결하면 브라우저에서 ROBOT_API_URL에 표시된 주소를 사용할 수 있습니다. 시뮬레이터 포트는 전달하지 않습니다.

VSCode Server의 포트 미리보기가 참가자별 HTTPS 주소를 제공한다면 그 주소의 스킴과 호스트·포트만을 ROBOT_BROWSER_ORIGIN으로 설정합니다. 예를 들어 끝에 /proxy/포트/가 붙는 경로 방식은 앱의 /api, /robot 절대 경로와 맞지 않습니다. 진행자는 루트 경로를 제공하는 포트 전달을 준비합니다. 04장의 터미널 자동 검증은 그 장에서 지정한 루프백 Origin으로 수행한 뒤, 브라우저 시연이 필요할 때 HTTPS 미리보기 Origin으로 전환합니다. 이 과정에서 새 보안 그룹 규칙이나 DNS 레코드를 만들 필요는 없습니다.

막혔을 때

현재 폴더가 workshop/.local/labs/<내 팀>/app인지 확인해 주세요.
이 폴더의 AGENTS.md와 package.json을 읽고 Node·Python 버전과 빌드 산출물을 점검하세요.
운영 폴더, 다른 참가자 폴더, 인증 파일은 읽거나 수정하지 마세요.
AWS 배포 없이 실패한 환경 검사와 바로 다음에 실행할 명령만 알려 주세요.

마칠 때 확인

• 필수 도구 검사와 참가자 사본 준비가 성공했다.
• ROBOT_LAB과 포트를 info에서 읽었다.
• npm run build와 MuJoCo import가 성공했다.
• 브라우저 접속 경로와 ROBOT_BROWSER_ORIGIN을 확인했다.

프롬프트: 환경과 작업 경계 확인

이전: 00. 이번 실습에서 만들 것 · 다음: 02. 로컬 물리 실습

AI CLI 프롬프트 카드

아래 프롬프트를 복사해 실습 EC2에서 선택한 Codex, Kiro CLI, Claude Code의 대화 입력창에 붙여넣습니다. Markdown 카드 다운로드

현재 폴더가 Robot Atlas 참가자 사본인지 먼저 pwd로 확인해 주세요.
예상 위치는 workshop/.local/labs/<내 팀>/app입니다.
이 폴더의 AGENTS.md와 package.json을 읽고 작업 경계를 확인하세요.

이번 요청은 환경 확인입니다.
- Node는 24.18.1 이상인 24 계열, Python은 3.11이어야 합니다.
- 참가자 info 결과에서 확인한 API·시뮬레이터 포트를 사용합니다.
- npm run build 후 dist/index.html과 build/server/main.js를 확인합니다.
- 참가자 .venv에서 MuJoCo 3.3.7 import를 확인합니다.
- 브라우저 접속 주소와 API의 PUBLIC_ORIGIN이 맞아야 합니다.

기존 .env나 인증 파일의 값을 출력하지 마세요.
운영 robot-arm 루트와 jeju-atlas, 다른 참가자 작업 공간을 변경하지 마세요.
운영 .env·.state·실행 기록·AWS 키를 복사하지 마세요.
설정이나 작업 공간이 이미 있으면 prepare를 다시 실행하거나 폴더를 지우지 마세요.
전역 Python·Node·AI CLI 설치를 바꾸지 마세요.
AWS 생성·배포·DNS 등록은 이 요청에 포함되지 않습니다.

실제로 확인한 항목, 실패한 항목, 다음 한 단계의 명령을 간단히 알려 주세요.
로컬 환경 확인을 AWS 모델 호출 성공으로 보고하지 마세요.