129 lines
5.2 KiB
Markdown
129 lines
5.2 KiB
Markdown
# Autonomy Studio LMS
|
|
|
|
Autonomy Studio LMS의 학생용 데스크톱 애플리케이션입니다. Electron 기반으로 동작하며, 학습 워크스페이스에서 ROS 2/NAV2 모듈 설치와 실행, 코드 편집, Git 연동, 터미널, 맵 및 시각화를 제공합니다.
|
|
|
|
로컬 PC 시뮬레이션과 원격 플랫폼 워크스페이스를 모두 지원합니다.
|
|
|
|
## 주요 기능
|
|
|
|
- 강좌, 학습 단계, 모듈 기반 워크스페이스 관리
|
|
- 로컬 및 원격 플랫폼의 모듈 설치, 빌드, 실행, 종료
|
|
- 코드 편집기, Git 소스 제어, 내장 터미널
|
|
- ROS 토픽 연결 상태와 모듈 간 발행/구독 관계 확인
|
|
- 2D/3D SLAM 맵 저장 및 주행 시각화
|
|
- Docker 기반 ROS 런타임과 SLAM ROS 브리지 관리
|
|
- 원격 플랫폼 에이전트와 연동한 워크스페이스 및 교보재 제어
|
|
|
|
## 프로젝트 구조
|
|
|
|
```text
|
|
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를 인식하지 못하면 모듈 실행이 실패합니다.
|
|
|
|
## 개발 환경 실행
|
|
|
|
```bash
|
|
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_` 변수에 넣으면 안 됩니다.
|
|
|
|
예시:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
## 빌드
|
|
|
|
```bash
|
|
# Electron main, preload, renderer 빌드
|
|
npm run build
|
|
|
|
# Linux AppImage 생성
|
|
npm run build:linux
|
|
```
|
|
|
|
패키징 결과물은 `dist/`에 생성됩니다. AppImage에는 아이콘, SLAM ROS 브리지, 실행 도구, 라이선스 리소스가 함께 포함됩니다.
|
|
|
|
운영 배포용 AppImage는 관리자 웹의 빌드 변수와 동일한 API 주소, 동일한 소스 커밋을 기준으로 빌드해야 합니다. Kubernetes의 LMS 웹 배포 환경 변수는 Electron AppImage에 런타임으로 주입되지 않습니다.
|
|
|
|
## 워크스페이스와 맵
|
|
|
|
모듈, 빌드 결과물, 저장 맵은 선택한 사용자 워크스페이스 루트 아래에 관리됩니다. SLAM 맵은 기본적으로 다음 경로에 저장됩니다.
|
|
|
|
```text
|
|
<workspace>/maps
|
|
```
|
|
|
|
앱은 해당 워크스페이스를 Docker 컨테이너의 `/workspace`로 마운트하고, SLAM 브리지에는 `SAVED_MAPS_PATH=/workspace/maps`를 전달합니다.
|
|
|
|
## GPU 가속
|
|
|
|
GPU 가속을 켠 상태에서 다음과 비슷한 오류가 발생하면 Docker GPU 런타임이 설정되지 않은 상태입니다.
|
|
|
|
```text
|
|
failed to discover GPU vendor from CDI
|
|
```
|
|
|
|
NVIDIA Container Toolkit을 설치하고 Docker를 재시작한 뒤 아래 명령이 정상 동작하는지 확인합니다.
|
|
|
|
```bash
|
|
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 주소와 원격 런타임 이미지 태그가 대상 환경과 일치하는지 확인합니다.
|