installation

설치

deb 파일 다운로드부터 첫 로그인 · 설치 마법사까지의 전 과정.

최근 확인 버전: v0.0.0

Easy Trainer는 Ubuntu 22.04 이상에서 동작하는 Debian 패키지(.deb) 형태로 배포됩니다. 설치는 3단계로 끝납니다.

  1. deb 파일 다운로드 · 설치 — 파일 매니저에서 더블클릭
  2. 런처 첫 실행 — 애플리케이션 메뉴에서 클릭, Google 로그인
  3. 설치 마법사 — 학습 서버 옵션 선택, Docker 이미지 빌드

시스템 요구사항

항목최소권장비고
OSUbuntu 22.04 LTSUbuntu 22.04 / 24.04 LTS다른 배포판은 미지원
RAM8 GB16 GB+학습 시 더 많이 권장
저장 공간20 GB50 GB+Docker 이미지(~12 GB) + 데이터셋
GPUNVIDIA, VRAM 4 GB+NVIDIA, VRAM 8 GB+학습·추론 모두 GPU 필수
네트워크인터넷 연결5 Mbps+모듈 다운로드, OAuth 인증

설치

    1. deb 파일을 다운로드합니다.

      다운로드 페이지 또는 GitHub Releases에서 easytrainer_<버전>_amd64.deb를 받습니다.

      다운로드 페이지에서 easytrainer_*.deb 받기

    2. 파일 매니저에서 deb 파일을 더블클릭합니다.

      Ubuntu의 기본 패키지 인스톨러(Software Install)가 열립니다. 우클릭이 필요하다면 Open With Other Application → Software Install을 선택하세요.

      Ubuntu Software Install — 설치 버튼

      Install 버튼을 누르고 사용자 비밀번호를 입력하면 설치가 진행됩니다.

런처 첫 실행

    1. 애플리케이션 메뉴에서 Easy Trainer를 실행합니다.

      키보드의 Super 키(보통 Windows 로고)를 누르거나 Activities를 클릭한 뒤 Easy Trainer로 검색해서 아이콘을 클릭합니다.

      Activities에서 Easy Trainer 검색

      런처가 시작되면서 자동으로 다음 3가지를 점검합니다.

      • 데이터/프로젝트 경로 권한 (/opt/easytrainer/)
      • Google 로그인 (디바이스 인증)
      • Docker 설치 여부

      하나라도 실패하면 빨간 다이얼로그를 띄우고 종료합니다.

    2. Google 계정으로 로그인합니다.

      런처가 자동으로 기본 브라우저를 열어 디바이스 등록 페이지로 이동시킵니다. 브라우저가 열리지 않으면 다이얼로그의 URL을 복사 버튼으로 복사해 직접 여세요.

      Easy Trainer 로그인 다이얼로그
      브라우저 OAuth 동의 화면

      브라우저에서 Google 로그인 후 이 기기 등록 버튼을 누르면 런처가 자동으로 인증을 완료하고 토큰을 ~/.easytrainer/auth.json에 저장합니다.

설치 마법사

처음 실행이면 5단계 설치 마법사가 자동으로 열립니다.

    1. 소프트웨어 사용권 계약 (EULA)

      설치 마법사 EULA 페이지

      본문을 읽고 동의함 체크박스를 켠 뒤 다음.

    2. 설치 준비 — 저장 공간 확인

      저장 공간 확인 페이지

      현재 여유 공간이 20 GB 이상이어야 진행됩니다. 부족하면 다음 버튼이 비활성화됩니다.

    3. 학습 서버 옵션 선택

      학습 서버 옵션 선택

      학습을 어디서 돌릴지 선택합니다. 기본값은 원격 모드입니다.

      • 원격 모드 (기본값) — 이 PC에 학습 서버를 설치하지 않습니다. Easy Trainer가 제공하는 원격 학습 서버를 사용해 학습 작업을 실행합니다. 자체 GPU가 학습에 부족하거나 별도 학습 PC를 두기 부담스러울 때 권장됩니다.
      • 로컬 모드 — 같은 PC에 학습 서버까지 함께 설치됩니다. 외부 통신 없이 모든 학습이 로컬에서 처리됩니다. 자체 GPU가 충분하고 데이터를 외부로 보내고 싶지 않을 때 선택하세요.

    4. 설치 진행

      설치 진행률

      다음 작업이 순차로 진행됩니다.

      • [INSTALL] docker compose build --no-cache — Docker 이미지 빌드
      • [GPU] NVIDIA Container Toolkit 설치/구성 (GPU 자동 구성)
      • [POST] Running DB migrations — SQLite 스키마 생성
      • [POST] Bringing up service — backend / frontend / ros2 컨테이너 기동
      • [MODULE] (i/N) <module_name> 다운로드 중 — 필수 모듈 자동 설치
      • [TRAIN-SERVER] ... — 학습 서버 다운로드/설치 (로컬 모드일 때)

      평균 진행 시간은 10–15분입니다. 네트워크 / 디스크 속도에 따라 차이가 납니다.

    5. 완료

      설치 완료

      Easy Trainer 실행하기 체크박스를 그대로 두고 완료를 누르면 메인 런처가 뜹니다.

메인 런처

메인 런처 floating bar

상단 우측의 두 점은 각각 Frontend / Backend 상태등입니다. 둘 다 초록불이 되면 브라우저에서 http://localhost:5173으로 접속해 운영자 UI를 사용할 수 있습니다.

floating bar의 7개 버튼:

버튼의미
⇆ 빠른 동기화개발용 코드 sync (일반 사용자는 건드리지 않음)
📁 불러오기외부에서 데이터셋·DB 가져오기
🧾 내보내기데이터셋·체크포인트 외부로 내보내기
📋 로그Launcher / Frontend / Backend / ROS 2 로그 4창 표시
🧩 모듈 관리로봇·센서·확장 모듈 설치/제거
🔥 학습 서버로컬 학습 서버 설치/실행/중지
✕ 종료EXIT / RESTART / STOP SERVICE

다음으로 빠른 시작 가이드를 따라 첫 데이터를 수집하고 학습까지 진행해 보세요.

자주 마주치는 문제

deb 파일을 GUI로 열 수 없을 때

App Center가 deb 파일을 처리하지 못하면 터미널에서 직접 설치할 수 있습니다.

sudo apt install ./easytrainer_<버전>_amd64.deb

런처가 "Docker가 설치되어 있지 않습니다"로 종료될 때

deb 패키지가 의존성 자동 설치에 실패한 경우입니다. 터미널을 열어 다음을 실행하세요.

sudo apt install -y docker.io docker-compose-plugin
sudo usermod -aG docker "$USER"

그리고 로그아웃 후 다시 로그인한 뒤 런처를 다시 실행합니다.

GPU가 컨테이너에서 안 보임

설치 마법사가 GPU 모드를 자동 구성하지만, 호스트의 NVIDIA 드라이버가 너무 오래되었거나 누락된 경우가 있습니다. 터미널에서 다음으로 확인합니다.

nvidia-smi

GPU 정보가 안 나오면 NVIDIA 드라이버를 설치한 뒤 PC를 재부팅합니다 (Software & Updates → Additional Drivers에서 GUI로 가능).

"DEVICE_ALREADY_BOUND" 오류

다른 PC에서 같은 Google 계정으로 이미 등록되어 있다는 뜻입니다. 홈페이지의 /dashboard로 가서 기존 기기를 **해제(unbind)**한 뒤 다시 시도하세요.

5173 / 5000 포트 충돌

다른 프로세스가 같은 포트를 점유 중이면 컨테이너가 뜨지 않습니다. 가장 간단한 해결책은 PC 재부팅입니다.

재설치 / 제거

가장 단순한 방법은 Software Center(Ubuntu의 앱 관리 GUI)에서 Easy Trainer를 검색해 제거 버튼을 누르는 것입니다.

데이터까지 완전히 지우려면 터미널에서:

bash scripts/clean_easytrainer.sh

관련 문서