Autonomy Studio LMS
Autonomy Studio LMS의 학생용 데스크톱 애플리케이션입니다. Electron 기반으로 동작하며, 학습 워크스페이스에서 ROS 2/NAV2 모듈 설치와 실행, 코드 편집, Git 연동, 터미널, 맵 및 시각화를 제공합니다.
로컬 PC 시뮬레이션과 원격 플랫폼 워크스페이스를 모두 지원합니다.
주요 기능
- 강좌, 학습 단계, 모듈 기반 워크스페이스 관리
- 로컬 및 원격 플랫폼의 모듈 설치, 빌드, 실행, 종료
- 코드 편집기, Git 소스 제어, 내장 터미널
- ROS 토픽 연결 상태와 모듈 간 발행/구독 관계 확인
- 2D/3D SLAM 맵 저장 및 주행 시각화
- Docker 기반 ROS 런타임과 SLAM ROS 브리지 관리
- 원격 플랫폼 에이전트와 연동한 워크스페이스 및 교보재 제어
프로젝트 구조
src/
main/ Electron main process, Docker/워크스페이스/원격 제어
preload/ renderer에 노출하는 IPC API
renderer/src/ React 사용자 인터페이스
resources/
slam-ros-bridge/ SLAM 및 시각화용 ROS 브리지
bin/ 패키징에 포함되는 실행 파일
licenses/ 배포 라이선스
요구 사항
- Node.js와 npm
- Docker Engine
- Git
- Linux AppImage 패키징 시 필요한 시스템 의존성
GPU 가속을 사용할 경우에는 NVIDIA 드라이버 외에 Docker용 NVIDIA Container Toolkit이 필요합니다. GPU 가속은 Docker 컨테이너에 --gpus all 옵션을 전달하므로, Docker 런타임이 GPU를 인식하지 못하면 모듈 실행이 실패합니다.
개발 환경 실행
cp .env.example .env
npm ci
npm run dev
renderer 개발 서버는 기본적으로 5176 포트를 사용합니다.
환경 변수
.env.example을 복사해 로컬 환경에 맞게 설정합니다.
| 변수 | 설명 |
|---|---|
VITE_API_BASE_URL |
LMS 백엔드 API 주소 |
VITE_LAUNCHER_API_BASE_URL |
런처/플랫폼 API 주소 |
LOCAL_AUTOWARE_BRIDGE_IMAGE |
로컬 Autoware ROS 브리지 이미지 |
LOCAL_NAV2_BRIDGE_IMAGE |
로컬 NAV2 ROS 브리지 이미지 |
LOCAL_NAV2_RUNTIME_IMAGE |
로컬 NAV2 런타임 이미지 |
LOCAL_SLAM_BRIDGE_IMAGE |
로컬 SLAM ROS 브리지 이미지 |
LOCAL_SLAM_RUNTIME_IMAGE |
로컬 SLAM 런타임 이미지 |
JETSON_AGENT_URL |
원격 Jetson 에이전트 주소 |
JETSON_AGENT_TOKEN |
원격 Jetson 에이전트 인증 토큰 |
JETSON_AUTOWARE_BRIDGE_IMAGE |
원격 Autoware ROS 브리지 이미지 |
JETSON_NAV2_BRIDGE_IMAGE |
원격 NAV2 ROS 브리지 이미지 |
JETSON_NAV2_RUNTIME_IMAGE |
원격 NAV2 런타임 이미지 |
VITE_ 접두사 변수는 renderer 번들에 포함됩니다. 운영 AppImage를 만들 때는 운영 API 주소로 빌드해야 하며, 토큰이나 비밀번호 같은 민감한 값은 VITE_ 변수에 넣으면 안 됩니다.
예시:
VITE_API_BASE_URL=https://workspace.autonomystudio.net/lms-api/api \
VITE_LAUNCHER_API_BASE_URL=https://portal-api.autonomystudio.net/api \
npm run build:linux
빌드
# Electron main, preload, renderer 빌드
npm run build
# Linux AppImage 생성
npm run build:linux
패키징 결과물은 dist/에 생성됩니다. AppImage에는 아이콘, SLAM ROS 브리지, 실행 도구, 라이선스 리소스가 함께 포함됩니다.
운영 배포용 AppImage는 관리자 웹의 빌드 변수와 동일한 API 주소, 동일한 소스 커밋을 기준으로 빌드해야 합니다. Kubernetes의 LMS 웹 배포 환경 변수는 Electron AppImage에 런타임으로 주입되지 않습니다.
워크스페이스와 맵
모듈, 빌드 결과물, 저장 맵은 선택한 사용자 워크스페이스 루트 아래에 관리됩니다. SLAM 맵은 기본적으로 다음 경로에 저장됩니다.
<workspace>/maps
앱은 해당 워크스페이스를 Docker 컨테이너의 /workspace로 마운트하고, SLAM 브리지에는 SAVED_MAPS_PATH=/workspace/maps를 전달합니다.
GPU 가속
GPU 가속을 켠 상태에서 다음과 비슷한 오류가 발생하면 Docker GPU 런타임이 설정되지 않은 상태입니다.
failed to discover GPU vendor from CDI
NVIDIA Container Toolkit을 설치하고 Docker를 재시작한 뒤 아래 명령이 정상 동작하는지 확인합니다.
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
GPU 설정이 준비되지 않은 PC에서는 앱 설정에서 GPU 가속을 끈 상태로 사용합니다.
로그와 문제 확인
- 앱 renderer 로그는 Electron의 사용자 로그 경로에
renderer.log로 기록됩니다. - 모듈 실행 실패는 워크스페이스 화면의 모듈 로그와 Docker 컨테이너 로그를 함께 확인합니다.
- 원격 플랫폼 문제는 에이전트 상태, Tailscale/Headscale 연결, ROS Domain ID, 원격 Docker 이미지를 순서대로 점검합니다.
보안 유의 사항
.env는 저장소에 커밋하지 않습니다.- 에이전트 토큰, API 키, 인증 정보는 빌드 변수 또는 별도 비밀 저장소로 관리합니다.
- 운영 배포 전에는 API 주소와 원격 런타임 이미지 태그가 대상 환경과 일치하는지 확인합니다.